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

我有一个模块,errors.py中定义了几个全局常量(注意:我知道Python没有常量,但我已经按照约定使用UPPERCASE)。

"""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如何记录这些常量?正如你可以看到我列出了一个文档字符串在他们之上,但我没有找到任何文档,表明这样做,我只是做了一个猜测。

不幸的是,变量(和常量)没有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可以拿起。

http://stackoverflow.com/questions/20227051/how-to-document-a-module-constant-in-python

本站文章除注明转载外,均为本站原创或编译
转载请明显位置注明出处:如何在Python中记录模块常量?