5

Numpy 文档字符串指南说：

冒号前面必须有一个空格，如果类型不存在则省略。

并举个例子：

Parameters
----------
x : type
    Description of parameter `x`.
y
    Description of parameter `y` (with type not specified)

另一方面， PEP8字面意思是冒号前的空格是错误的：

# Wrong:

code:int  # No space after colon
code : int  # Space before colon

我知道这适用于代码，而不适用于文档字符串，但为什么不保持一致呢？

问题

在冒号前加一个空格的动机是什么？

它似乎违反了印刷规则和 python 约定（或至少是直觉）。

4

1 回答 1

4

为什么冒号前有空格？

因为在 NumPy 中，一些文档字符串部分中的语法定义与 reStructuredText定义列表的语法一致。请注意，语法与 reST 标记规范完全相同：

定义列表

每个定义列表项都包含一个术语、可选的分类器和一个定义。术语是一个简单的单行单词或短语。 可选的分类器可以跟在同一行的术语之后，每个都在一个内联的“:”（空格、冒号、空格）之后。

Syntax diagram:

+----------------------------+
| term [ " : " classifier ]* |
+--+-------------------------+--+
   | definition                 |
   | (body elements)+           |
   +----------------------------+

这是有道理的，因为 numpydoc 清楚地说明了它对 PEP 257 的预期合规性。

numpydoc 文档字符串指南

概述

我们主要遵循此处描述的标准 Python 样式约定：

  • 文档字符串约定 - PEP 257

PEP 表明它的意图是文档字符串应该使用 reST 结构编写：

摘要，PEP 287

此 PEP 建议采用 reStructuredText 标记作为 Python 文档字符串中结构化纯文本文档的标准标记格式

这也可以通过引用 numpydoc 贡献者的决定来验证，例如：

问题 #87

现在 numpydoc 格式实际上首先是有效的（只是对某些标记结构进行了一些特殊解释），例如参数字段是一个定义列表，其中类型是“分类器”（http://docutils.sourceforge.net/docs/ref /rst/restructuredtext.html#definition-lists）。我认为保留这个属性是值得的，行尾反斜杠可以做到（它们根本不会出现在字符串本身中），而建议的“识别缩进”语法却没有。

几个地方也提到了同样的道理：

公关#107

这可能属于“如果它没有损坏，就不要修复它”的类别，但我注意到我们奇怪地使用块引用作为参数列表而不是定义列表。更新：现在这个 PR 建议默认使用定义列表，并切换到使用旧版块引用。

冒号前加空格的具体规则见numpydoc.validate.py源码，文档中：

内置验证检查

"PR10": 'Parameter "{param_name}" requires a space before the colon '
       "separating the parameter name and type"

总之，要使用 reST 编写文档字符串（符合 PEP 257），在reST 正文元素中没有太多列表标记结构可供选择。定义列表是最好的选择，因为它的术语/分类器语法完全适合 Python 对象的名称/类型列表。

解决问题中提出的直观反对意见：

另一方面，PEP8 字面意思是冒号前的空格是错误的

是的，但是 PEP 8 提到的函数和变量注释不涉及文档字符串（文档字符串）！这些用于签名和变量声明。

于 2021-02-13T17:18:34.993 回答