为什么定义在 NumPy 文档字符串部分的冒号前有一个空格？

Question

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 约定（或至少是直觉）。

Answer 1

为什么冒号前面有一个空格？

因为在 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/restructedtext.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 提到的函数和变量注释并不是指文档字符串 (docstrings)！这些用于签名和变量声明。