我在哪里可以找到 PEP 257 文档字符串约定的正确示例？答案

【问题标题】：Where can I find proper examples of the PEP 257 Docstring Conventions?我在哪里可以找到 PEP 257 文档字符串约定的正确示例？
【发布时间】：2012-04-04 19:16:06
【问题描述】：

PEP 257 says：

在所有文档字符串之前和之后插入一个空行（单行或多行）记录一个类——一般来说，类的方法之间用一个空行分隔，并且 docstring 需要从第一个方法偏移一个空行；为了对称，在类头和类之间放一个空行文档字符串。

但我似乎找不到任何实际实现此功能的代码。

我检查了 Python 2.6 提供的几个标准模块，甚至专门搜索了提到 Guido 名字的模块。但即使是 rietveld 代码审查工具的代码也不符合恕我直言（参见例如http://code.google.com/p/rietveld/source/browse/upload.py）：

class CondensedHelpFormatter(optparse.IndentedHelpFormatter):
   """Frees more horizontal space by removing indentation from group
      options and collapsing arguments between short and long, e.g.
      '-o ARG, --opt=ARG' to -o --opt ARG"""

   def format_heading(self, heading):
     return "%s:\n" % heading

这个多行文档字符串之前没有空行，之后的空行在右引号之外。

来自/usr/lib64/python2.6/site.py 的这个类之前没有空行，但在右引号前后都有一个空行。

class _Helper(object):
    """Define the built-in 'help'.
    This is a wrapper around pydoc.help (with a twist).

    """

    def __repr__(self):

是否有可用于演示 PEP 257 的示例？

提前致谢

【问题讨论】：

“列表”/“投票”问题不是 Stack Overflow 的主题。另外，我看不出这与您要解决的实际问题有何关系。
我很欣赏您所做的研究，当然可以找到官方文档字符串格式的示例，但目前尚不清楚这会带来什么好处。有一些不正确的文档字符串的例子，其中一些甚至可能是由 Guido 编写的。如果您想编写正确的，只需遵循指南（PEP 文档本身甚至提供示例）。简而言之，这里有什么意义？为什么您需要（更多）这种格式的示例？
@agf：这不是一个民意调查。我相信 PEP 在某些领域并不是 100% 明确的，我正在寻找能够阐明这些部分的示例。具体来说，我正在寻找与 PEP 匹配的类的文档字符串示例。 halst 的代码在类文档字符串之前和之后显示空行，并在文档字符串本身的末尾显示一个空行。这是我什至没有考虑过的另一种选择。
@iulius-caesar：也许更具体的问题是什么被认为是“所有文档字符串前后的空白行”。是在开/关引号之前还是之后？
@Bram：我认为添加这样的细节可能有助于这个问题得到有用的答案。

标签： python coding-style

【解决方案1】：

不是直接的答案，但如果你想遵守 PEP257，你可以使用我写的工具： https://github.com/halst/pep257

我也震惊地看到有多少代码（也在标准库中）甚至没有尝试遵守 PEP257。

可能大多数人认为他们的 docstring-style 是有道理的，我也认为PEP257 风格有些别扭，但是在使用了一段时间后我爱上它了，并认为这是编写文档字符串最漂亮的方式。我总是在我能做的每一个方面都遵循 PEP257，并编写了这个工具，以便更多的人可以看到他们如何改进自己的风格。

举个例子，我对 PEP8 和 pep8 tool 有过一次有趣的经历：当我第一次阅读 PEP8 时，我很喜欢它并且认为我会遵循它，但是当我在 pep8 上尝试我的代码时我对我离 PEP8 有多远以及在修复这些样式错误后我的代码看起来有多好感到震惊。

希望大家对pep257也有类似的体验，从此开始愉快地关注PEP257。

【讨论】：

@Bram 有趣！您对 PEP 的哪些部分有不同的解释？只是好奇。也许我的解释有误。
在阅读您的 pep257.py 之前，我从未考虑过引号之前和之前的空白行。
@Bram 请注意，文档字符串之前的空行是用于类的。对于函数，仅当函数具有由空行分隔的代码组时才适用。

【解决方案2】：

据我所知，您链接到的文档说：

在记录一个类的所有文档字符串（单行或多行）之后插入一个空行——一般来说，类的方法由一个空行相互分隔，并且文档字符串需要从第一个方法偏移一个空行。

（强调我的）

因此，您提供的示例都是正确的，因为它们在文档字符串后有一个空行，因此用空行分隔下一个方法声明。

【讨论】：

【解决方案3】：

这里是一些 pep(Python Enhancement Proposal) python 示例示例首先我们选择要使用的版本，因为这个示例与 pep-8 最相似。所以我们必须提供函数描述、参数和返回类型...

def foo(bar, spam, eggs):
        """
        Some function

        :param bar: parameter that requires description
        :param spam: parameter that requires description
        :param eggs:
        :return xyz: parameter description
        """

According google style 包含一个优秀的 python 样式指南。这提供了比 PEP-257 更好的指导，参考链接：google style guide

def sample_fun(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

【讨论】：