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

不幸的是，变量(和常量)没有docstrings。毕竟，该变量只是一个整数的名称，并且你不想要像对函数或类对象一样附加一个docstring到数字1。

如果你看看stdlib中几乎任何模块，如pickle，你会看到他们使用的唯一文档是注释。是的，这意味着帮助(pickle)只显示这一点：

DATA

APPEND = b'a'

APPENDS = b'e'

…

…完全忽略了评论。如果你希望你的文档显示在内置的帮助中，你必须将它们添加到模块的docstring，这是不完全理想的。

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

#: Indicates some unknown error.

API_ERROR = 1

多个#：在任何赋值语句之前的行，或者在语句右边的一个#：注释，与由autodoc拾取的对象上的docstrings有效地工作。其中包括处理内联rST，并为变量名自动生成rST标头;没有什么额外的你需要做的工作。

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

枚举实例(不是flufl.enum，但stdlib / backport版本)甚至可以有docstrings：

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

虽然他们不幸地没有出现在帮助(MyErrors.MISSING_PARAMS)，它们是文档字符串，Sphinx autodoc可以拿起。