标准的Python文档字符串格式是什么?[关闭]


887

我已经看到了几种用Python编写文档字符串的样式,是否有正式或“同意的”样式?


6
python.org/dev/peps/pep-0008有一整节专门介绍文档字符串
mechanical_meat 2010年

30
我觉得这个问题是不够明确,因为PEP-257和PEP-8的建立只对文档字符串的基础,但如何epydocdoxygensphinx?没有人有任何统计资料,在这样的情况下,太多的选择可能会受到伤害,其中一个会取代其他统计吗?
sorin 2011年

1
@sorin,我也想知道最常见的标记是什么。但是我认为答案是,它们之间没有一个真的很普通:人们倾向于直接查看Python源代码,而不是转换为html。因此,保持一致但以针对人类可读性进行了优化的方式(无显式标记)为最有用。
12

3
PyCharm以一种非常有趣的方式自动完成,我认为这是对运行它的指令的很好的实现:def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Matteo Ferla

1
在VS Code文档解析器的默认情况下,以下哪个答案是最合适的?
威廉·恩崔肯

Answers:


1019

格式

可以按照其他文章所示的几种格式编写Python文档字符串。但是未提及默认的Sphinx文档字符串格式,该格式基于reStructuredText(reST)。您可以在此博客文章中获得有关主要格式的一些信息。

请注意,reST是PEP 287推荐的

以下是文档字符串的主要使用格式。

-Epytext

从历史上看,像Javadoc这样的样式很普遍,因此它被当作Epydoc(具有称为Epytext格式)生成文档的基础。

例:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

-reST

如今,可能更流行的格式是Sphinx用于生成文档的reStructuredText(reST)格式。注意:默认在JetBrains PyCharm中使用它(在定义方法后键入三引号,然后按Enter键)。默认情况下,它也用作Pyment中的输出格式。

例:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- 谷歌

Google有自己常用的格式。Sphinx也可以解释它(即使用Napoleon插件)。

例:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

甚至更多的例子

-Numpydoc

请注意,Numpy建议根据Google格式使用自己的numpydoc,并且Sphinx可以使用。

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

转换/生成

可以使用Pyment之类的工具自动为尚未记录的Python项目生成文档字符串,或者将现有文档字符串(可以混合多种格式)从一种格式转换为另一种格式。

注意:这些示例摘自Pyment文档


10
我可能会补充说,reST是JetBrains PyCharm中默认使用的内容,只需在定义方法后键入三引号并按Enter。jetbrains.com/pycharm/help/creating-documentation-comments.html
费利佩·阿尔梅达

12
最全面的答案包括对历史的了解和当前的最佳实践。现在,我们所需要的只是某种社区对新的“最佳”格式的动感,以及一些社区的努力,以从其他所有方式创建到新的迁移工具,以便我们实际上可以发展最佳实践。
BobHy

2
哟@ daouzli,google样式链接是404。我相信是正确的。您也可以添加狮身人面像谷歌风格的例子。好答案顺便说一句。编辑:我自己编辑了你的答案。
2016年

4
好答案。我敢说您可以在PyCharm(JetBrains)中更改默认文档字符串格式:设置->工具-> Python集成工具->文档字符串格式。祝好运!
Jackssn

4
令我惊讶的是,没有人评论第一行文本:目前严格来说这是正确的,但我认为首选的方法是将其放在三引号后的第一行。PEP 8和PEP 257在几乎所有示例中都这样做。PEP 287可以按照您的方式来做,但是根据我的经验,这并不常见。
Lapinot

323

谷歌的风格指南中包含一个优秀的Python风格指南。它包括可读文档字符串语法的约定,约定比PEP-257提供更好的指导。例如:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

我想将此扩展为在参数中也包含类型信息,如本Sphinx文档教程中所述。例如:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

37
我发现“文档字符串中的签名”样式非常冗长和冗长。对于Python 3+,使用功能注释是一种更简洁的方法。如果它使用伪强类型,那就更糟了:Python在鸭子类型上要好得多。
Evpok 2012年

27
是的,但是至少它暗示了人们期望的是哪种鸭子,而且大多数开发人员还没有使用Python 3
Anentropic

3
@Evpok个人而言,我不喜欢函数注释。要在其中使用类,您可能必须进行不必要的导入,要在其中使用字符串,可能会很快用尽水平空间来描述它们。到目前为止,我还没有看到将它们用于任何用途的意义。
OdraEncoded,2014年

5
@ Nathan,Google的样式指南建议使用描述性而非声明性的注释,例如,“从Bigtable中获取行”而不是“从Bigtable中获取行”。因此,将“计算...”更改为“计算...”将使您的示例与其余注释(即“返回”和“提高”)更加一致。
gwg

2
尼特:遵循Google风格,使用描述性而不是命令式,即“计算...”和“添加...”
sbeliakov

228

PEP-257中的文档字符串约定比PEP-8更为详细。

但是,文档字符串似乎比其他代码区域更具个性。不同的项目将有自己的标准。

我倾向于总是包含docstrings,因为它们倾向于演示如何使用该函数以及该函数的执行速度非常快。

无论字符串的长度如何,我都希望保持一致。我喜欢缩进和间距一致时的代码外观。这意味着,我使用:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

过度:

def sq(n):
    """Returns the square of n."""
    return n * n

并倾向于在较长的文档字符串中省略第一行的注释:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

意思是我发现像这样开始的文档字符串很乱。

def sq(n):
    """Return the squared result. 
    ...

90
请注意,PEP-8特别指出,文档字符串应作为命令/指令而不是描述来编写。"""Return the squared result"""而不是"""Returns the squared result"""。尽管个人而言,尽管PEP说了什么,但我还是写了Tim的情况。
坎·杰克逊

63
我也不同意该建议(使用命令式时态),因为对于超过一句话的任何内容,它开始听起来都是尴尬的。此外,您在描述一个功能,而不是告诉读者该怎么做。
mk12 2012年

14
注意:说明性而非说明性文档字符串的规范实际上出现在PEP-257中,而不是PEP-8中。 我来自Java的传统,当时我在描述函数,但是当我的编程范例从面向对象转换为过程式时,我终于开始使用命令式时态。当我开始使用pycco生成文化编程风格的文档时,为什么建议命令式时态变得非常明显。您应该根据自己的范例进行选择。
karan.dodia 2013年

25
当务之急是语法心情。(对不起)
Denis Drescher 2014年

5
@ Mk12 Git提交消息也应作为命令而不是描述来编写。而且他们还“ 描述 ”了代码更改,“没有告诉读者该怎么做”。因此,我认为将描述作为命令编写只是惯例。
一张照片,2015年

58

显然没有人提到它:您还可以使用Numpy Docstring Standard。它在科学界被广泛使用。

用于解析Google样式文档字符串的Napolean狮身人面像扩展名(在@Nathan的答案中建议)也支持Numpy样式文档字符串,并对两者进行简短的比较

最后一个基本示例给出了它的外观:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

2
NumPy格式IMHO占用了过多的垂直空间,这在宽屏显示器上是很少的(除非您使用旋转90度的显示器,但我想大多数人都不会),因此,就可读性和功能而言,IMHO Google格式是一个不错的选择。
Semanino

3
我想这有点主观。一旦有了更复杂的文档字符串(具有不同的部分,示例等,因此无论使用哪种格式,无论如何都要占用大量垂直空间),我都会发现numpydoc格式更易于阅读/结构更好。
joris

2
我个人觉得这样长的文档字符串最好放在文档中,而不是源代码中,如果太长了,它们最终会阻碍模块的可读性。
乔纳森·哈特利

12

PEP-8是官方的python编码标准。它包含有关文档字符串的部分,该部分引用了PEP- 257-文档字符串的完整规范。


8
在“我应该如何正确记录参数,返回值,引发的异常等”的上下文中提到PEP-257是一个笑话-它说的不是一个单词(尽管代码示例显示了一些)。IMHO Google格式在可读性和功能方面是不错的选择。
Semanino '18

9

是Python;一切顺利。考虑如何发布您的文档。除了您的源代码读者以外,文档字符串是不可见的。

人们真的很喜欢浏览和搜索网络上的文档。为此,请使用文档工具Sphinx。这是记录Python项目的实际标准。该产品非常漂亮-请访问https://python-guide.readthedocs.org/en/latest/。“ 阅读文档 ”网站将免费托管您的文档。


22
我通常使用它ipython来测试驱动一个库,这使得读取文档字符串变得非常简单—我所要输入的只是your_module.some_method_im_curious_about?得到的每一个漂亮的打印输出,包括文档字符串。
Thanatos

8
API的用户或正在编写插件的用户都可能查看代码并需要理解它们。我发现注释在Python中比在Java或C#中更为重要,因为未声明类型。如果评论能大致说明正在传递和返回哪种鸭子,这将大有帮助。(否则,您实际上必须遍历所有代码并合计一个给定的参数必须...在此处可迭代...在那儿支持索引...最后支持数字减法...啊哈!基本上是int array。发表评论会有所帮助!)
Jon Coombs 2014年

嗯不 文档字符串不是不可见的,这很重要。如果help在记录的函数/方法/类上运行该函数,则会看到docstring (即使您只能访问已编译的模块,也可以执行此操作)。我个人认为选择文档字符串约定时应牢记这一点(即,应按原样阅读)。
凌晨

7

我建议使用Vladimir Keleshev的pep257 Python程序根据PEP-257Numpy Docstring Standard检查您的文档字符串,以描述参数,返回值等。

pep257将报告您与标准的差异,称为pylint和pep8。


在“我应该如何正确记录参数,返回值,引发的异常等”的上下文中提到PEP-257是一个笑话-它说的不是一个单词(尽管代码示例显示了一些)。NumPy格式IMHO占用了过多的垂直空间,这在宽屏显示器上是很少的(除非您使用旋转90度的显示器,但我想大多数人都不会),因此,就可读性和功能而言,IMHO Google格式是一个不错的选择。
Semanino

1
@Semanino我在pep257程序的上下文中提到了Numpy Docstring标准,而不是PEP-257。该程序现在称为pydocstyle。pydocstyle允许您执行一些numpydoc检查,例如pydocstyle --select=D4 tmp.py检查一系列文档字符串内容问题,包括节命名。
FinnÅrupNielsen
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.