web-dev-qa-db-fra.com

Comment documenter une constante de module en Python?

J'ai un module, errors.py, dans lequel plusieurs constantes globales sont définies (note: je comprends que Python n'a pas de constantes, mais je les ai définies par convention en utilisant 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

À l'aide de reStructuredText, comment puis-je documenter ces constantes? Comme vous pouvez le constater, j'ai énuméré une chaîne de documentation au-dessus d'eux, mais je n'ai trouvé aucune documentation indiquant cela, je l'ai juste fait comme une supposition.

pythonpython-sphinxrestructuredtext
39
skyler

Malheureusement, les variables (et les constantes) n'ont pas de docstring. Après tout, la variable est juste un nom pour un entier et vous ne voudriez pas attacher une chaîne de documentation au nombre 1 comme vous le feriez pour un objet de fonction ou de classe.

Si vous examinez presque tous les modules de la bibliothèque stdlib, tels que pickle , vous verrez que la seule documentation qu'ils utilisent est des commentaires. Et oui, cela signifie que help(pickle) ne montre que ceci:

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

… Complètement ignorer les commentaires. Si vous souhaitez que vos documents apparaissent dans l'aide intégrée, vous devez les ajouter à la docstring du module, ce qui n'est pas tout à fait idéal.

Mais Sphinx peut faire plus que l'aide intégrée. Vous pouvez le configurer pour extraire les commentaires sur les constantes ou utiliser autodata pour le faire de manière semi-automatique. Par exemple:

#: Indicates some unknown error.
API_ERROR = 1

Plusieurs lignes #: avant toute instruction d'affectation, ou un seul commentaire #: à la droite de l'instruction, fonctionnent de la même manière que docstrings sur les objets capturés par autodoc. Ce qui inclut la gestion de la RST en ligne et la génération automatique d’un en-tête RST pour le nom de la variable; il n'y a rien de plus que vous ayez à faire pour que cela fonctionne.

En remarque, vous voudrez peut-être envisager d’utiliser un enum au lieu de constantes séparées comme celle-ci. Si vous n'utilisez pas Python 3.4 (ce que vous n'êtes probablement pas encore…), il existe un paquet backport.enum pour 3.2+, ou flufl.enum (qui n'est pas identique, mais similaire, car était la principale inspiration du module stdlib) pour 2.6+.

Les instances enum (pas flufl.enum, mais la version stdlib/backport) peuvent même avoir des 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

Bien qu'ils ne s'affichent malheureusement pas dans help(MyErrors.MISSING_PARAMS), ce sont des documents que l'autodoc Sphinx peut récupérer.

50
abarnert

Vous pouvez utiliser hash + colon pour documenter les attributs (au niveau de la classe ou du module).

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

Ceci sera pris en compte certains générateurs de documents. 

Un exemple ici, impossible de trouver un meilleur/ Propriétés du module de document Sphinx

16
Mikko Ohtamaa

Si vous mettez une chaîne after la variable, sphinx la prendra comme documentation de la variable. Je sais que cela fonctionne parce que je le fais partout. Comme ça:

FOO = 1
"""
Constant signifying foo.

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

La directive pylint indique à pylint d'éviter de marquer la documentation comme étant une instruction sans effet.

16
Louis

C'est une question plus ancienne, mais j'ai remarqué qu'il manquait une réponse pertinente.

Vous pouvez aussi inclure une description des constantes dans la docstring du module via .. py: data :: . Ainsi, la documentation est également disponible via l’aide interactive. Sphinx rendra bien cela.

"""
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.
"""
16
Robert Jørgensgaard Engdahl

Je pense que vous n'avez pas de chance ici.

Python ne supporte pas directement les docstrings sur les variables: aucun attribut ne peut être attaché à des variables et récupéré de manière interactive comme l'attribut __doc__ sur les modules, les classes et les fonctions.

La source .

3
Johnsyweb

Écrire uniquement parce que je n'ai pas vu cette option dans les réponses jusqu'à présent:

Vous pouvez également définir vos constantes comme des fonctions qui renvoient simplement la valeur constante souhaitée lors de l'appel, par exemple:

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

De cette façon, ils seront un peu "plus constants" d'une part (moins préoccupés par la réaffectation) et offriront également la possibilité d'une documentation régulière, comme pour toute autre fonction.

0
Gábriel