¿Existen convenciones para los comentarios del módulo Python?

Question

Tengo entendido que un docstring de módulo solo debe proporcionar una descripción general de lo que hace un módulo y los detalles como el autor y la versión solo deben contenerse en los comentarios del módulo.

Sin embargo, he visto lo siguiente en los comentarios y docstrings:

__author__ = "..." 
__version__ = "..." 
__date__ = "..." 

¿Dónde está la ubicación correcta para poner artículos como estos? ¿Qué otras variables __[name]__ son comunes a la lista en la parte superior de los módulos?

Answer 1

Ellos no son más que convenciones, aunque convenciones que se utilizan ampliamente bastante. Consulte this description de un conjunto de requisitos de metadatos de Python.

__version__ se menciona en el Python Style Guide.

En cuanto a docstrings, ¡hay un PEP just for you!

El docstring para un módulo debe generalmente una lista de las clases, excepciones y funciones (y cualesquiera otros objetos) que son exportados por el módulo, con un resumen de una línea de cada uno. (Estos resúmenes generalmente dan menos detalle de la línea de resumen en docstring del objeto.) La cadena de documentación para un paquete (es decir, la cadena de documentación de init módulo .py del paquete ) debe también una lista de los módulos y subpaquetes exportado por el paquete.

Answer 2

Sugeriría no preocuparse por __author__, __version__, etc. Esos atributos son manejados por cualquier sistema de control de versión decente de todos modos. Solo agréguelas si necesita tener esa información en un sistema de producción, donde el código fuente ya se ha exportado fuera del sistema de control de versiones.

Answer 3

Usted puede echar un vistazo a:

• Epydoc, más concretamente su pre-definido fields.
• Pydoc