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

【问题标题】：Why do definitions have a space before the colon in NumPy docstring sections?为什么定义在 NumPy 文档字符串部分的冒号前有一个空格？
【发布时间】：2020-09-21 20:07:42
【问题描述】：

Numpy docstring guide 说：

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

并举个例子：

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

【问题讨论】：

在reddit找到类似的讨论
为什么要一致？ numpy 开发人员不是 Python 的。您的 pep8 案例实际上来自 annotations 加法，python.org/dev/peps/pep-0526（从 2016 年开始）。
Python 文档字符串指南，PEP 257 使用两个破折号，例如"real -- 实数部分（默认 0.0）"（虽然这不是正式定义的）。
与注释相关的是 PEP 484 类型提示，它使用非空格约定 (name: str)。这些提示可以使用mypy等工具进行处理。

标签： python numpy restructuredtext docstring numpydoc

【解决方案1】：

为什么冒号前有空格？

因为在 NumPy 中，一些 docstring sections 中的语法定义与 reStructuredText Definition List 的语法一致。请注意，语法与以下的 reST 标记规范完全相同：

Definition Lists

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

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

有道理，因为 numpydoc 清楚地说明了其符合 PEP 257 的预期。

numpydoc 文档字符串指南

Overview

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

文档字符串约定 - PEP 257

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

Abstract, PEP 287

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

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

Issue #87

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

在几个地方提到了相同的推理：

PR #107

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

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

Built-in Validation Checks

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

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

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

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

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

【讨论】：