Подтвердить что ты не робот

Как документировать константу модуля в 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, как я могу документировать эти константы? Как вы можете видеть, я перечислил docstring над ними, но я не нашел никакой документации, которая указывает на это, я только что сделал это как предположение.

Ответ 1

К сожалению, переменные (и константы) не имеют docstrings. В конце концов, переменная является просто именем целого числа, и вы не захотите присоединить docstring к числу 1, как это было бы с функцией или объектом класса.

Если вы посмотрите почти на любой модуль в stdlib, например pickle, вы увидите, что единственная документация, которую они используют, это комментарии. И да, это означает, что help(pickle) показывает это только:

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

... полностью игнорируя комментарии. Если вы хотите, чтобы ваши документы отображались во встроенной справке, вы должны добавить их в docstring модуля, что не совсем идеально.

Но Sphinx может делать больше, чем встроенная справка. Вы можете настроить его для извлечения комментариев по константам или использовать autodata, чтобы сделать это полуавтоматически. Например:

#: Indicates some unknown error.
API_ERROR = 1

Несколько строк #: перед любой операцией присваивания или один комментарий #: справа от оператора, работают эффективно так же, как 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

Хотя они, к сожалению, не отображаются в help(MyErrors.MISSING_PARAMS), они являются docstrings, которые Spinx autodoc может забрать.

Ответ 2

Вы можете использовать hash + colon для документирования атрибутов (класс или уровень модуля).

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

При этом будут получены некоторые генераторы документов.

Пример здесь не смог найти лучшего Свойства модуля документа Sphinx

Ответ 3

Если вы поместите строку после переменной, то sphinx подберет ее как документацию переменных. Я знаю, что это работает, потому что я делаю это повсюду. Вот так:

FOO = 1
"""
Constant signifying foo.

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

Директива pylint сообщает pylint о том, чтобы не помечать документацию как выражение без эффекта.

Ответ 4

Это старый вопрос, но я отметил, что соответствующий ответ отсутствовал.

Или вы можете просто включить описание констант в docstring модуля через .. py: data::. Таким образом, документация также доступна через интерактивную справку. Сфинкс сделает это красиво.

"""
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.
"""

Ответ 5

Я думаю, тебе здесь не повезло.

Python не поддерживает непосредственно docstrings для переменных: нет атрибута, который может быть привязан к переменным и получен в интерактивном режиме, как атрибут __doc__ для модулей, классов и функций.

Source.