Question

在所有文档字符串之前和之后插入一个空行（一行或一行）记录一个班级的多线路 - 一般来说，是班级的方法通过一个空行彼此分开，并且 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。

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

作为一个例子，我对PEP8和pep8 tool有一个有趣的体验：当我第一次阅读PEP8时，我喜欢它并且思考我遵循它，但当我在pep8上尝试我的代码时我对PEP8的距离感到震惊，以及修复这些样式错误后我的代码看起来有多好。

我希望人们与pep257有相似的经历，并且从此开始愉快地开始关注PEP257。

Answer 2

据我所知，你链接的文件说：

在所有文档字符串（单行或多行）之后插入一个空白行来记录一个类 - 一般来说，类的方法是由一个单独的空行，文档字符串需要通过空行从第一个方法偏移。

（强调我的）

因此，您提供的示例都是正确的，因为它们在docstring后面有一个空行，因此将下一个方法声明与空行分开。

Answer 3

这是一些pep（Python增强建议）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
        """

根据Google样式，其中包含有关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

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

3 个答案: