最常见的Python docstring格式有哪些？

我见过几种不同风格的Python编写docstring，最流行的风格是什么？

588407 次浏览
小开

Docstring约定在PEP-257中，比PEP-8详细得多。

然而，文档字符串似乎比其他代码领域更加个人化。不同的项目将有自己的标准。

我倾向于始终包含文档字符串，因为它们倾向于快速演示如何使用该函数及其功能。

我更喜欢保持一致，不管字符串的长度如何。我喜欢缩进和行间距一致时的代码外观。这意味着，我使用：

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

google风格指南包含一个出色的Python风格指南。它包括可读docstring语法的约定，提供比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
小开

它是Python；什么都可以。考虑如何发布你的留档。除了源代码的读者之外，文档字符串是不可见的。

人们真的很喜欢在网络上浏览和搜索留档。要做到这一点，请使用留档工具狮身人面像。它是记录Python项目的事实标准。产品很漂亮-看看https://python-guide.readthedocs.org/en/latest/。网站阅读文档将免费托管您的文档。

小开

显然没有人提到它：你也可以使用Numpy文档字符串标准配置。它在科学界被广泛使用。

用于解析Google风格文档字符串的Napolean sphinx扩展（在@Nathan的回答中推荐）也支持Numpy风格的文档字符串，并对两者进行了简短的比较。

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

def func(arg1, arg2):"""Summary line.
Extended description of function.
Parameters----------arg1 : intDescription of arg1arg2 : strDescription of arg2
Returns-------boolDescription of return value
See Also--------otherfunc : some related other function
Examples--------These are written in doctest format, and should illustrate how touse the function.
>>> a=[1,2,3]>>> print [x + 3 for x in a][4, 5, 6]"""return True
小开
最佳答案

格式

如其他帖子所示，Python文档字符串可以按照多种格式编写。然而，没有提到默认的Sphinx文档字符串格式，它基于//重新构造文本。您可以在这篇博客文章中获得有关主要格式的一些信息。

请注意，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）格式。注意：默认情况下，它在JetBrains PyCharm中使用（在定义方法并按回车键后键入三重引号）。默认情况下，它也被用作P的输出格式。

示例：

"""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 kindof very exhautive numpydoc format docstring.
Parameters----------first : array_likethe 1st param name `first`second :the 2nd paramthird : {'value', 'other'}, optionalthe 3rd param, by default 'value'
Returns-------stringa value in a string
Raises------KeyErrorwhen a key errorOtherErrorwhen an other error"""

转换/生成

可以使用像填充这样的工具自动生成文档字符串到尚未记录的Python项目，或者将现有的文档字符串（可以混合多种格式）从一种格式转换为另一种格式。

注意：示例取自粘贴留档

小开

我建议使用Vladimir Keleshev的pep257 Python程序来检查您的文档字符串与PEP-257和Numpy文档字符串标准配置的关系，以描述参数、返回等。

PET257将报告您与标准的分歧，并被称为pylint和PET8。


提交答案