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

Question

我有一个模块，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如何记录这些常量？正如你所看到的，我已经在他们上面列出了一个文档字符串，但我没有找到任何表明这样做的文档，我只是猜测它。

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（你可能还没有...），那么有一个用于3.2+或backport.enum的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

虽然不幸的是它们没有出现在help(MyErrors.MISSING_PARAMS)中，但它们是Sphinx autodoc可以提供的文档字符串。

Answer 2

您可以使用散列+冒号来记录属性（类或模块级别）。

  #: Use this content as input for moo to do bar
  MY_CONSTANT = "foo"

这将是一些文件生成器。

这里的一个例子，找不到更好的一个Sphinx document module properties

Answer 3

如果你在变量后放一个字符串，那么sphinx将把它作为变量的文档。我知道它有效，因为我在整个地方都这样做。像这样：

FOO = 1
"""
Constant signifying foo.

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

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

Answer 4

这是一个较老的问题，但我注意到缺少相关的答案。

或者您可以通过.. py:data::在模块的docstring中包含常量的描述。这样，文档也可以通过交互式帮助获得。狮身人面像将很好地渲染。

"""
Docstring for my module.

.. data:: API_ERROR

    Indicates some unknown error.

.. data:: BAD_REQUEST

    Indicates that the request was bad in some way.

.. data:: MISSING_PARAMS

    Indicates that the request is missing required parameters.
"""

Answer 5

我觉得你在这里运气不好。

Python不直接支持变量上的文档字符串：没有属性可以附加到变量并以交互方式检索，就像模块，类和函数上的__doc__属性一样。

Source。

Answer 6

写作只是因为到目前为止我还没有在答案中看到这个选项：

您还可以将常量定义为在调用时仅返回所需常量值的函数，例如：

def get_const_my_const() -> str:
    """Returns 'my_const'."""
    return "my_const"

这样他们一方面会“更加稳定”（不用担心重新分配），他们也会提供定期文档的机会，就像其他任何功能一样。