Python Docstring: relance vs relances

Question

J'utilise PyCharm IDE qui aide à créer des docstrings conformes à PEP0257. Il fournit deux attributs dont je ne comprends pas entièrement la distinction/utilisation entre:

• :raise Exception: exception explanation here
• :raises Exception: exception explanation here

Quand utiliserais-je raise comme opposé à raises dans ma docstring? Plus précisément, si une classe nécessite un argument qui n'a pas été fourni et déclenche un TypeError, qui devrait être utilisé pour documenter cela?

Answer 1

TL; DR

raises est utilisé pour décrire les éventuelles exceptions levées. raise est reconnu par Sphinx lors de l'exécution de l'autodoc et est identique à raises.

Explication complète

PyCharm aide à utiliser différents styles de commentaires de docstring.

J'en utilise souvent trois:

1. Format NumPy
2. format Google
3. Sphinx (bien plus qu'un format)

Dans tous ceux-ci, il existe une section spéciale pour Raises que vous pouvez voir dans une ancienne version des tests de code PyCharm:

1. NumPy simple
2. Google simple

L'implémentation de SphinxDocString nous pouvons voir ici il existe de nombreux mots clés qui peuvent être reconnus. Ces balises renvoient ensuite à la liste des RAISES_TAGS qui peut être trouvé ici .

J'espère que cette information est utile.