metodos - ¿Cómo documentar una constante de módulo en Python?

pydoc function documentation

Question

Tengo un módulo, errors.py en el que se definen varias constantes globales (nota: entiendo que Python no tiene constantes, pero las he definido por convención usando MAYÚSCULAS).

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

Usando reStructuredText ¿cómo puedo documentar estas constantes? Como puede ver, he enumerado una docstring encima de ellos, pero no he encontrado ninguna documentación que indique que lo haya hecho, solo lo he hecho como una suposición.

Answer 1

Creo que no tienes suerte aquí.

Python no admite directamente docstrings en variables: no hay ningún atributo que se pueda adjuntar a variables y recuperar de forma interactiva, como el atributo __doc__ en módulos, clases y funciones.

Source

Answer 2

Desafortunadamente, las variables (y las constantes) no tienen cadenas de documentos. Después de todo, la variable es solo un nombre para un entero, y no le gustaría adjuntar una docstring al número 1 como lo haría con una función u objeto de clase.

Si observa casi cualquier módulo en el stdlib, como pickle , verá que la única documentación que utilizan es comentarios. Y sí, eso significa que la help(pickle) solo muestra esto:

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

... ignorando por completo los comentarios. Si desea que sus documentos aparezcan en la ayuda integrada, debe agregarlos a la carpeta de documentos del módulo, lo cual no es exactamente lo ideal.

Pero Sphinx puede hacer más de lo que la ayuda integrada puede. Puede configurarlo para extraer los comentarios en las constantes o usar los datos autodata para hacerlo de forma semiautomática. Por ejemplo:

#: Indicates some unknown error.
API_ERROR = 1

Múltiples #: líneas antes de cualquier instrucción de asignación, o un único #: comentario a la derecha de la instrucción, funcionan de manera efectiva igual que las cadenas de documentos en objetos recogidos por autodoc. Que incluye manejar rST en línea y generar automáticamente un encabezado rST para el nombre de la variable; no hay nada más que tenga que hacer para que funcione.

Como nota al margen, es posible que desee considerar el uso de una enum lugar de constantes separadas como esta. Si no estás usando Python 3.4 (que probablemente aún no estás ...), hay un paquete backport.enum para 3.2+, o flufl.enum (que no es idéntico, pero es similar, ya que fue la principal inspiración para el módulo stdlib) para 2.6+.

Las instancias de Enum (no flufl.enum , pero la versión stdlib / backport) incluso pueden tener cadenas de documentos:

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

Aunque desafortunadamente no aparecen en la help(MyErrors.MISSING_PARAMS) , son documentos que Sphinx autodoc puede recuperar.

Answer 3

Esta es una pregunta anterior, pero noté que faltaba una respuesta relevante.

O simplemente puede incluir una descripción de las constantes en la documentación del módulo a través de ... py: data :: . De esta forma, la documentación también está disponible a través de la ayuda interactiva. Sphinx lo renderizará muy bien.

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

Puede usar hash + dos puntos para documentar atributos (clase o nivel de módulo).

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

Esto será recogido algunos generadores de documentos.

Un ejemplo aquí, no pudo encontrar una mejor propiedad de módulo de documento de Sphinx

Answer 5

Si coloca una cadena después de la variable, entonces sphinx la recogerá como la documentación de la variable. Sé que funciona porque lo hago por todos lados. Me gusta esto:

FOO = 1
"""
Constant signifying foo.

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

La directiva pylint le dice a pylint que evite marcar la documentación como una afirmación sin efecto.