标准的 Python 文档字符串格式是什么?

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

答案

格式

可以按照其他文章所示的几种格式编写 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 文档

Google 样式指南包含出色的 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

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. 
    ...

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

用于解析 Google 样式文档字符串的 Napolean sphinx 扩展(在 @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

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

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

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

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

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