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

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

不幸的是，变量（和常量）没有文档字符串。毕竟，变量只是整数的名称，并且您不希望

1

像在函数或类对象上那样将文档字符串附加到数字上。

如果您看一下stdlib中的几乎所有模块，例如

pickle

，您都会看到它们唯一使用的文档是注释。是的，这意味着

help(pickle)

仅显示以下内容：

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

……完全忽略了评论。如果要使文档显示在内置帮助中，则必须将它们添加到模块的文档字符串中，这并不完全理想。

---

但是Sphinx可以做的比内置帮助还多。您可以配置它以提取常量的注释，或用于

autodata

半自动执行注释。例如：

#: Indicates some unknown error.API_ERROR = 1

#:

任何赋值语句之前的多行或

#:

该语句右边的单个注释，都与自动文档拾取的对象上的文档字符串有效地相同。其中包括处理内联rST，并为变量名称自动生成rST标头；无需任何额外的工作即可完成这项工作。

---

作为附带说明，您可能需要考虑使用

enum

诸如此类的而不是单独的常量。如果您不使用Python
3.4（可能尚未使用……），则有一个

backport.enum

3.2或以上版本的软件包，或者

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可以拾取的文档字符串。