如何在 Python 中记录模块常量? [英] How to document a module constant in Python?

问题描述

我有一个模块，errors.py，其中定义了几个全局常量(注意:我知道 Python 没有常量，但我已经按照约定使用大写字母定义了它们).

I have a module, errors.py in which several global constants are defined (note: I understand that Python doesn't have constants, but I've defined them by convention using 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 如何记录这些常量?正如你所看到的，我在它们上面列出了一个文档字符串，但我没有找到任何表明这样做的文档，我只是猜测.

Using reStructuredText how can I document these constants? As you can see I've listed a docstring above them, but I haven't found any documentation that indicates to do that, I've just done it as a guess.

推荐答案

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

Unfortunately, variables (and constants) do not have docstrings. After all, the variable is just a name for an integer, and you wouldn't want to attach a docstring to the number 1 the way you would to a function or class object.

如果您查看 stdlib 中的几乎所有模块，例如 pickle，您将看到他们使用的唯一文档是注释.是的，这意味着 help(pickle) 只显示这个:

If you look at almost any module in the stdlib, like pickle, you will see that the only documentation they use is comments. And yes, that means that help(pickle) only shows this:

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

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

… completely ignoring the comments. If you want your docs to show up in the built-in help, you have to add them to the module's docstring, which is not exactly ideal.

但是 Sphinx 可以做的比内置帮助做的更多.您可以将其配置为提取常量的注释，或使用 autodata 半自动完成.例如:

But Sphinx can do more than the built-in help can. You can configure it to extract the comments on the constants, or use autodata to do it semi-automatically. For example:

#: Indicates some unknown error.
API_ERROR = 1

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

Multiple #: lines before any assignment statement, or a single #: comment to the right of the statement, work effectively the same as docstrings on objects picked up by autodoc. Which includes handling inline rST, and auto-generating an rST header for the variable name; there's nothing extra you have to do to make that work.

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

As a side note, you may want to consider using an enum instead of separate constants like this. If you're not using Python 3.4 (which you probably aren't yet…), there's a backport.enum package for 3.2+, or flufl.enum (which is not identical, but it is similar, as it was the main inspiration for the stdlib module) for 2.6+.

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

Enum instances (not flufl.enum, but the stdlib/backport version) can even have 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

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

Although they unfortunately don't show up in help(MyErrors.MISSING_PARAMS), they are docstrings that Sphinx autodoc can pick up.

这篇关于如何在 Python 中记录模块常量?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！