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

Question

PEP 257说:

在记录类的所有文档字符串(单行或多行)之前和之后插入一个空行 - 一般来说,类的方法通过一个空行彼此分开,并且docstring需要从第一种方法是一个空白行; 为了对称,在类头和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的示例？

提前致谢

Answer 1

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

我也很震惊地看到有多少代码(也在标准库中)甚至没有尝试遵守PEP257.

也许大多数人认为他们的文档风格是有道理的,我也认为PEP257风格有些尴尬,但在使用它一段时间后我爱上了它,并认为这是最美好的方式写docstrings.我总是在每个方面都遵循PEP257,并编写了工具,以便更多人能够看到他们如何改进自己的风格.

举个例子,我对PEP8和pep8工具有一个有趣的体验:当我第一次阅读PEP8时,我喜欢它,并认为我遵循它,但当我在pep8上尝试我的代码时,我感到震惊的是我离PEP8有多远,以及如何我修复这些样式错误后,我的代码更好.

我希望人们对pep257有类似的经验,并且从此开始愉快地开始关注PEP257.