如何在 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 如何记录这些常量？如您所见，我在它们上方列出了一个文档字符串，但我还没有找到任何指示这样做的文档，我只是猜测而已。

原文由 skyler 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

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

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

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

……完全无视评论。如果你想让你的文档出现在内置帮助中，你必须将它们添加到模块的文档字符串中，这并不是很理想。

---

但是 Sphinx 可以做的不仅仅是内置帮助。您可以将其配置为提取常量注释，或使用 autodata 半自动执行。例如：

 #: Indicates some unknown error.
API_ERROR = 1

任何赋值语句之前的多个 #: 行，或语句右侧的单个 #: 注释，与 autodoc 拾取的对象上的文档字符串一样有效地工作。其中包括处理内联 rST，并为变量名自动生成 rST 标头；您无需做任何额外的工作即可完成这项工作。

---

作为旁注，您可能需要考虑使用 enum 而不是像这样的单独常量。如果你没有使用 Python 3.4（你可能还没有……），有一个 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 可以获取的文档字符串。

原文由 abarnert 发布，翻译遵循 CC BY-SA 3.0 许可协议

Answer 2

如果你在变量 后面 放一个字符串，sphinx 会把它作为变量的文档。我知道它有效，因为我到处都这样做。像这样：

 FOO = 1
"""
Constant signifying foo.

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

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

原文由 Louis 发布，翻译遵循 CC BY-SA 3.0 许可协议