python3 - python__ doc__
Python Docstring: raise vs. raises (1)
TL; DR
raises se utiliza para describir las posibles excepciones que se plantean. Sphinx reconoce el raise cuando ejecuta autodoc y es el mismo que raises .
Explicación completa
PyCharm ayuda en el uso de algunos estilos diferentes de comentarios de docstring.
Tres que utilizo a menudo son:
- Formato NumPy
- Formato de Google
- Sphinx (mucho más que un formato)
En todos estos, hay una sección especial para Raises que puede ver en una versión anterior de las pruebas de código de PyCharm:
La implementación para SphinxDocString que podemos ver aquí hay numerosas palabras clave que pueden reconocerse. Esas etiquetas luego enlazan a la lista de RAISES_TAGS que se pueden encontrar here .
Espero que esta información sea útil.
Utilizo el IDE de PyCharm que ayuda a crear cadenas de documentación compatibles con PEP0257. Proporciona dos atributos que no entiendo completamente la distinción / uso entre:
:raise Exception: exception explanation here-
:raises Exception: exception explanation here
¿Cuándo usaría raise como se opone a raises en mi docstring? Específicamente, si una clase requirió un argumento que no se proporcionó y genera un TypeError , ¿cuál debería usarse para documentarlo?