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

Question

Numpy docstring guide说:

The colon must be preceded by a space, or omitted if the type is absent.

并举了一个例子:

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

Why a space before the colon?

因为在 NumPy 语法定义里面有些 docstring sections与 reStructuredText 的语法一致 Definition List .
请注意，语法与 reST 标记规范完全相同:

Definition Lists

Each definition list item contains a term, optional classifiers, and a definition. A term is a simple one-line word or phrase. Optional classifiers may follow the term on the same line, each after an inline " : " (space, colon, space).

Syntax diagram:

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

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

numpydoc docstring guide

Overview

We mostly follow the standard Python style conventions as described here:

• Docstring Conventions - PEP 257

并且 PEP 声明其意图是应该使用 reST 构造编写文档字符串:

Abstract, PEP 287

This PEP proposes that the reStructuredText markup be adopted as a standard markup format for structured plaintext documentation in Python docstrings

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

Issue #87

Right now numpydoc format is actually valid rst (just with some special interpretation of certain markup constructs), e.g. the parameters field is a definition list where the type is a "classifier" (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists). I would argue that it is worthwhile to keep this property, which end-of-line backslashes do (they simply do not appear in the string itself), whereas the proposed "recognize indentation" syntax does not.

同样的道理在几个地方提到:

PR #107

This probably falls under the category of "if it ain't broke, don't fix it", but I note that we're strangely using blockquotes for parameter listings instead of definition lists. UPDATED: now this PR proposes to use definition lists by default, with a switch to use the legacy blockquotes.

冒号前有空格的具体规则见 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 对象的名称/类型列表。

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

In the other hand, PEP8 literally says that a space before colon is wrong

是的，但是 PEP 8 中提到的函数和变量注释并不是指文档字符串(docstrings)!这些用于签名和变量声明。