如何在 Python 中记录模块常量？

Question

我有一个模块，errors.py，其中定义了几个全局常量（注意：我知道 Python 没有常量，但我已经按照约定使用大写来定义它们）。

"""Indicates some unknown error."""
API_ERROR = 1

"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2

"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3

使用 reStructuredText 如何记录这些常量？如您所见，我在它们上方列出了一个文档字符串，但我没有找到任何表明这样做的文档，我只是猜测。

Answer 1

不幸的是，变量（和常量）没有文档字符串。毕竟，该变量只是一个整数的名称，您不希望将文档字符串附加到数字 1 上，就像附加到函数或类对象一样。

如果您查看 stdlib 中的几乎所有模块，例如 pickle，您会发现它们使用的唯一文档是 cmets。是的，这意味着help(pickle) 只显示这个：

DATA
    APPEND = b'a'
    APPENDS = b'e'
    …

... 完全无视 cmets。如果您希望您的文档显示在内置帮助中，则必须将它们添加到模块的文档字符串中，这并不理想。

---

但 Sphinx 可以做的比内置帮助更多。您可以将其配置为提取常量上的 cmets，或使用 autodata 半自动完成。例如：

#: Indicates some unknown error.
API_ERROR = 1

在任何赋值语句之前有多个#: 行，或者在语句右侧的单个#: 注释，其工作方式与自动文档拾取的对象上的文档字符串相同。其中包括处理内联 rST，并为变量名自动生成 rST 标头；你不需要做任何额外的事情来完成这项工作。

---

作为旁注，您可能需要考虑使用enum，而不是像这样的单独常量。如果你没有使用 Python 3.4（你可能还没有……），有一个用于 3.2+ 的 backport.enum 包，或 flufl.enum（不完全相同，但相似，因为它是主要灵感对于 stdlib 模块）2.6+。

枚举实例（不是flufl.enum，而是stdlib/backport 版本）甚至可以有文档字符串：

class MyErrors(enum.Enum):
    """Indicates some unknown error."""
    API_ERROR = 1

    """Indicates that the request was bad in some way."""
    BAD_REQUEST = 2

    """Indicates that the request is missing required parameters."""
    MISSING_PARAMS = 3

虽然很遗憾它们没有出现在 help(MyErrors.MISSING_PARAMS) 中，但它们是 Sphinx autodoc 可以获取的文档字符串。

Answer 2

如果您在变量之后 放置一个字符串，那么 sphinx 会将其作为变量的文档。我知道它有效，因为我到处都这样做。像这样：

FOO = 1
"""
Constant signifying foo.

Blah blah blah...
"""  # pylint: disable=W0105

pylint 指令告诉 pylint 避免将文档标记为无效语句。

Answer 3

这是一个较老的问题，但我注意到缺少相关答案。

或者您可以通过.. py:data:: 在模块的文档字符串中包含对常量的描述。这样，文档也可以通过交互式帮助获得。 Sphinx 会很好地渲染它。

"""
Docstring for my module.

.. data:: API_ERROR

    Indicates some unknown error.

.. data:: BAD_REQUEST

    Indicates that the request was bad in some way.

.. data:: MISSING_PARAMS

    Indicates that the request is missing required parameters.
"""

Answer 4

您可以使用哈希 + 冒号来记录属性（类或模块级别）。

#: Use this content as input for moo to do bar
MY_CONSTANT = "foo"

这将由 一些 文档生成器获取。

这里有一个例子，找不到更好的：Sphinx document module properties

Answer 5

我认为你在这里不走运。

Python 不直接支持变量上的文档字符串：没有属性可以附加到变量并以交互方式检索，例如模块、类和函数上的 __doc__ 属性。

Source.

Answer 6

以下内容适用于 Sphinx 2.4.4：

在foo.py：

API_ERROR = 1
"""int: Indicates some unknown error."""

然后记录它：

.. automodule:: foo.py 
    :members:

Answer 7

Sphinx Napoleon Python documentation extension 允许在属性部分记录模块级变量。

每https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html：

Attributes
----------
module_level_variable1 : int
    Module level variables may be documented in either the ``Attributes``
    section of the module docstring, or in an inline docstring immediately
    following the variable.

    Either form is acceptable, but the two should not be mixed. Choose
    one convention to document module level variables and be consistent
    with it.

Answer 8

写作只是因为到目前为止我还没有在答案中看到这个选项：

您还可以将常量定义为在调用时简单地返回所需常量值的函数，例如：

def get_const_my_const() -> str:
    """Returns 'my_const'."""
    return "my_const"

这样一来，它们一方面会“更加稳定”（不必担心重新分配），而且它们还提供了定期记录文档的机会，就像任何其他功能一样。