Get best of the week

PEP 257俄语。（文档字符串协议）

哈Ha有时候，您想尽可能地使自己沉迷于该语言并理解其所有微妙之处。对于Python，最好的方法之一是阅读官方网站上的文档和PEP。当时我没有这样做，因为我无法理解许多“技术”方面，而且俄语翻译没有变体。现在，我决定自己翻译PEP-257，它告诉您正确的代码文档，因为可以肯定的是，这将有助于初学者更好地理解编写代码的真正“ Python”方法。我将代码示例翻译成俄语，但这只是为了更好地传达其含义。在实际编程中，尝试用英语编写文档行。我还马上说，作为“文档字符串”一词的同义词，我使用了“文档”和“文档行”这两个词。好吧，让我们继续翻译本身。

p257
标题：Docstrings协议
作者：大卫·古德格（David Goodger）<在python.org上的古德>，吉多·范·罗苏姆（Guido van Rossum）在python.org上的[吉多]
讨论：python.org上的doc-sig
状态：活性
一种：信息性
创建时间：2001年5月29日
出版物：2001年6月13日

注解


该PEP记录了与Python文档字符串的使用相关的语义和约定。

理由


该PEP的目的是标准化文档行的高级结构：描述它们应包含的内容并进行解释（我们将不讨论实际的标记语法）。PEP不包含严格的准则，但是建议：
“传统惯例提供了清晰，一致，易于维护的方式，并养成了良好的编程习惯。但是它们不会强迫您违背自己的意愿。这是Python！”

Tim Peters在comp.lang.python上，2001年6月16日

如果您避免普遍接受的协议，那么您会在最糟糕的情况下着眼睛。但是有些应用程序（例如Docutils之类的文档系统）可以让您在了解协议并遵守协议的情况下取得更好的结果。

规格


什么是文档字符串？


文档字符串是字符串文字，它是模块，函数，类或方法定义中的第一条语句。处理此对象的特殊__doc__属性时，此字符串可用。

所有库以及它们导出的函数和类都必须具有docstring。公共方法（包括__init__构造函数）也必须具有文档。包本身可以记录在其相应目录中的__init__.py文件中。

在代码其他地方找到的字符串文字也可以起到文档作用。它们无法被Python字节码编译器识别，并且在程序执行期间不能用作对象属性（即，它们在__doc__中缺少信息）。但是，可以使用其他软件工具检索另外两种类型的文档行：

  1. 在模块，类或__init__级别上简单分配后立即出现的字符串文字称为“属性文档字符串”。（属性文档字符串）
  2. 在另一行文档之后立即出现的字符串文字称为“其他文档行”。（其他文档字符串）

有关属性和附加文档字符串的更多详细信息，请参见PEP 258，“ Docutils项目规范”。

[大约 ed。[PEP 258的说明]
def f(x):
    """  docstring   __doc__ ."""
    """
     "additional docstrings",   , 
        Docutils.
    """
    return x**2

f.a = 1
""" "attribute docstrings"   : f.a"""

为了保持一致性，请始终在文档行周围使用““”三重双引号“”“。如果您使用反斜杠字符（“ \”），请在文档中使用r“”“原始双引号字符串”“”。对于包含Unicode字符的文档字符串，请使用u“”“三重双引号中的Unicode字符串”“”。[大约 unicode字符串在python 3.x中已失去其含义。]

docstring有两种形式：单行和多行。

单行文档行


单行字符串用于明显的情况，它们实际上应该在同一行上。例如：

def kos_root():
    """    root KOS"""
    global _kos_root
    if _kos_root: return _kos_root
    ...

备注：

  • . .
  • , . docstring .
  • , .
  • — «», . (« », « »), . , : « ...».

    « » «Return pathname» «Returns pathname». PEP-257 , .
  • «», / ( ). :

    def function(a, b):
    """function(a, b) -> list"""

    , C ( ), . . - :

    def function(a, b):
    def function(a, b):
    """ X   ."""

    ( -, « X» !)

    , : « », «description» . , , .



多行文档由一个摘要行组成，该摘要行具有与单行docstring相同的结构，后跟一个空行，然后是一个更复杂的描述。 “摘要行”可以通过自动文档使用；因此，将其放在一行上然后在一行上通过是非常重要的。总结行会在左引号后立即写入，但允许进行连字符，并从下一行开始。 [大约这句话之后，我感到很高兴，因为有些人努力向我证明在任何情况下都无法进行转移：-)]同时，整个文档字符串的缩进应与第一行的开头引号相同（请参见示例）下面）。

在该类中使用的所有文档（单行或多行）之后留空行；一般来说，类方法必须用一个空行彼此分隔，因此类文档行也应以这种方式与第一个方法分隔。

脚本的文档（独立程序）是“关于正确使用”的消息，当使用无效或缺少的参数（或使用“ -h”选项获得“帮助”）调用脚本时，可能会打印该文档。这样的文档行应描述脚本参数的功能和语法，以及所使用的环境变量和文件。该消息可能看起来很复杂（手册有几个全屏显示），但是同时对于新用户来说应该很方便，以便他们可以正确使用该命令。另外，该手册应为经验丰富的用户提供所有参数和自变量的清晰描述。

模块文档通常应包含使用该库导出的类，异常和函数（以及任何其他重要对象）的列表，以及每一个的一行说明。 （通常，此摘要所提供的详细信息少于对象本身的文档字符串中的摘要行）。软件包说明文件（即__init__.py中的模块docstring）也应描述并列出主要软件包导出的模块和子软件包。

函数或方法的文档应描述其行为，参数，返回值，副作用，异常以及何时调用它们（如果有）的限制。您还必须指定可选参数。应该阐明关键参数是否是接口的一部分。

类文档应总结其行为并列出公共方法以及实例变量。如果该类具有带有附加接口的子类，则必须单独指定此接口（但本文档中也包括所有内容）。对于__init__方法，类构造函数必须具有自己的单独文档行。独立（个体）方法应具有自己的文档。

如果一个类是后代，并且其行为主要是从主类继承的，则有必要在其文档中提及这一点并描述可能的差异。使用动词“ override”表示方法已更改，因此将不会调用超类方法。如果子类方法调用超类方法（除了其自身的行为），则使用动词“ extends”。

不要使用Emacs约定大写提及函数参数或方法。 Python区分大小写，并且在通过键传递参数名称时有时会使用参数名称，因此文档必须包含实际的变量名称。最好在单独的行上列出每个参数。例如：

def complex(real=0.0, imag=0.0):
    """  .

     :
    real --   (  0.0)
    imag --   (  0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...


如果整个文档字符串都不适合该行，则可以将右引号放在单独的行上。因此，可以使用Emacs命令：fill-paragraph

文档字符串处理


文档行处理工具应从第二个开始，删除等于所有非空行的最小缩进数目的相同缩进数目。文档第一行中的任何缩进都不重要，将被删除。保留文档行中后面各行的相对缩进。空行应从文档行的开头和结尾删除。

由于代码比单词准确得多，因此该算法的实现如下：

def trim(docstring):
    if not docstring:
        return ''
    #     (  Python)
    #      :
    lines = docstring.expandtabs().splitlines()
    #    (   ):
    indent = sys.maxsize
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    #   (   ):
    trimmed = [lines[0].strip()]
    if indent < sys.maxsize:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    #       :
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    #    :
    return '\n'.join(trimmed)

译者注
, python3 sys.maxint sys.maxsize, .


以下示例中的文档包含两个换行符，因此长度为三个。第一行和最后一行为空：

def foo ():
    """
       .
    """

我们说明：

>>> print repr(foo.__doc__)
'\n        .\n    '
>>> foo.__doc__.splitlines()
['', '        .', '    ']
>>> trim(foo.__doc__)
'    .'

因此，在处理之后，以下文档行将等效：

def foo():
    """ 
     .
    """

def bar():
    """
     
     .
    """

译者注
inspect, , : inspect.cleandoc(function.__doc__)

More articles:


All Articles