Python Docstring: raise vs. raises

Question

Ich benutze die PyCharm IDE, die beim Erstellen von PEP0257-konformen Docstrings hilft. Es verfügt über zwei Attribute ich nicht ganz verstehen, die Unterscheidung/Verwendung zwischen:

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

Wann würde ich raise verwenden zu raises in meinem docstring entgegensetzt? Insbesondere, wenn eine Klasse ein Argument benötigt, das nicht bereitgestellt wurde, und eine TypeError auslöst, die verwendet werden sollte, um das zu dokumentieren?

Answer 1

TL; DR

raises wird verwendet, die möglichen Ausnahmen zu beschreiben angehoben. raise wird von Sphinx erkannt, wenn autodoc ausgeführt wird, und entspricht raises.

vollständige Erklärung

PyCharm hilft ein paar verschiedene Arten von Docstring Kommentare zu verwenden.

Drei, die oft ich verwende, sind:

1. NumPy Format
2. Google Format
3. Sphinx (viel mehr als ein Format)

In all diesen gibt es einen speziellen Bereich für Raises ist Das können Sie in einer älteren Version der PyCharm-Code-Tests sehen:

1. Simple NumPy
2. Simple Google

Die Implementierung für SphinxDocString können wir see here dort gibt es zahlreiche Keywords, die erkannt werden können. Diese Tags verlinken dann auf die Liste RAISES_TAGS, die here gefunden werden kann.

Ich hoffe, dass diese Informationen nützlich sind.