关于编码风格：什么是标准的Python文档字符串格式？


What is the standard Python docstring format?

我见过几种不同的用python编写docstring的风格，有正式的还是"同意的"风格？

相关讨论

格式

python docstring可以按照其他文章所示的几种格式编写。但是，没有提到默认的sphinx docstring格式，它基于restructuredtext(rest)。你可以得到一些关于短裙主要格式的信息。

注意，其余部分由PEP 287推荐。

下面是用于docstring的主要格式。

-外文文本

历史上，类似javadoc的风格很流行，因此它被作为epydoc(名为Epytext格式)生成文档的基础。

例子：

1
2
3
4
5
6
7
8
"""
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使用它来生成文档。注意：默认情况下，它在JetBrains Pycharm中使用(在定义方法后键入三个引号，然后按Enter键)。默认情况下，它也用作pyment中的输出格式。

例子：

1
2
3
4
5
6
7
8
"""
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
"""

谷歌

谷歌有自己的格式，这是经常使用的。它也可以由斯芬克斯解释(即使用拿破仑插件)。

例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
"""
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.
"""

更多的例子

- NuMyPoc

请注意，numpy建议使用自己的numpydoc，它基于Google格式，可供sphinx使用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
"""
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文档

相关讨论

谷歌风格指南包含一个优秀的python风格指南。它包括用于可读docstring语法的约定，提供了比PEP-257更好的指导。例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
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文档教程中所述。例如：

1
2
3
4
5
6
7
def add_value(self, value):
   """Add a new value.

       Args:
           value (str): the value to add.
   """
    pass
相关讨论

docstring约定在PEP-257中，比PEP-8更详细。

然而，docstring似乎比代码的其他区域更个人化。不同的项目将有自己的标准。

我倾向于总是包含docstring，因为它们倾向于演示如何使用该函数以及它的作用非常迅速。

不管绳子的长度如何，我都喜欢保持一致。我喜欢在缩进和间距一致时如何编写代码。这意味着，我使用：

1
2
3
4
5
def sq(n):
   """
    Return the square of n.
   """
    return n * n

超过：

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

在较长的docstrings中，往往会忽略对第一行的评论：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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

这意味着我发现像这样开始的文档字符串是混乱的。

1
2
3
def sq(n):
   """Return the squared result.
    ...
相关讨论

显然没有人提到它：您也可以使用numpy-docstring标准。它广泛应用于科学界。

  • numpy格式的规范以及一个示例
  • 您有一个sphinx扩展名来呈现它：numpydoc
  • 一个呈现的docstring有多漂亮的例子：http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

napolean sphinx扩展用于解析Google风格的docstring(在@nathan的答案中推荐)也支持numpy风格的docstring，并对两者进行了简短的比较。

最后是一个基本的例子来说明它是什么样子的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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
相关讨论

PEP-8是官方的python编码标准。它包含一个关于docstrings的部分，它引用了PEP-257——一个完整的docstrings规范。

相关讨论

它是Python，什么都有。考虑如何发布文档。除了源代码的读者之外，DocStrings是不可见的。

人们真的喜欢在网上浏览和搜索文档。为此，请使用文档工具sphinx。它实际上是记录Python项目的标准。产品很漂亮-请看https://python-guide.readthedocs.org/en/latest/。阅读文档的网站将免费托管您的文档。

相关讨论

我建议使用Vladimir Keleshev的pep257 python程序根据pep-257和numpy docstring标准检查docstring，以描述参数、返回等。

PEP257将报告您与标准的差异，称为皮林特和PEP8。

相关讨论

python的官方风格在pep-8中列出。

相关讨论