Encabezado de archivo Python

El encabezado de un archivo Python es documentación opcional al principio del archivo fuente. Un proyecto puede usar un formato común para explicar el propósito, el uso previsto, los requisitos y la licencia de un script; Python no exige ningún encabezado en particular. Incluye solo los datos que ayuden a entender o ejecutar el archivo y sigue las convenciones del proyecto.

Por qué usar un formato de encabezado común en Python

Un encabezado coherente ofrece contexto útil antes de que el lector examine la implementación. Puede indicar el propósito del script, quién lo mantiene, cómo ejecutarlo y qué requisitos importantes tiene de entorno de ejecución o dependencias. Un aviso de licencia también puede aclarar cómo se permite usar el código, siempre que refleje la licencia real del proyecto.

El formato es una convención del equipo, no una característica del lenguaje Python. Un script pequeño y de uso puntual quizá solo necesite una breve descripción del módulo, mientras que una herramienta de línea de comandos distribuida puede beneficiarse de notas sobre su uso y dependencias. La coherencia ayuda cuando varios archivos comparten un repositorio, pero copiar campos que no corresponden añade ruido y puede dejar información obsoleta.

Componentes del encabezado de un archivo Python

Elige los componentes según cómo se ejecuta y mantiene el archivo. Un encabezado suele combinar metadatos del intérprete, un docstring del módulo y comentarios para los lectores.

Shebang

Una línea shebang es una marca en la primera línea, como #!/usr/bin/env python3. En los sistemas que la reconocen, al ejecutar un script ejecutable mediante su ruta, se usa el intérprete que selecciona env. Es útil para scripts de línea de comandos en sistemas tipo Unix, pero no hace falta cuando el archivo se inicia con un comando como python script.py. Esta línea no instala Python ni selecciona un entorno para todas las formas de ejecutar el archivo.

Declaración de codificación

Los archivos de código fuente de Python 3 usan UTF-8 de forma predeterminada, por lo que normalmente no hace falta declarar la codificación. Si un archivo fuente usa otra codificación por compatibilidad con una herramienta o un entorno específicos, Python reconoce una declaración como # -*- coding: latin-1 -*- en la primera o la segunda línea. La declaración debe coincidir con la codificación real del archivo; no es una marca general que permita leer cualquier texto.

Docstring del módulo y comentarios

Un docstring del módulo es un literal de cadena al principio del módulo, después de cualquier shebang o comentario de codificación. Describe el módulo y está disponible en __doc__. Úsalo para indicar brevemente el propósito y aportar contexto útil sobre el módulo. Los comentarios normales pueden incluir notas sobre mantenimiento, uso, dependencias, versión o licencia; Python no interpreta esos comentarios automáticamente como metadatos.

Las importaciones van después del docstring del módulo y antes de las demás instrucciones ejecutables del módulo. Si se necesitan importaciones, una convención habitual es agrupar primero las de la biblioteca estándar, luego los paquetes de terceros y, por último, las del proyecto, con una línea en blanco entre los grupos.

El encabezado puede indicar cómo ejecutar un script, qué paquetes necesita o cuál es la versión mínima de Python, si esos datos son relevantes. Mantén los requisitos sincronizados con la configuración real del proyecto. Incluye un aviso de licencia solo si coincide con la licencia elegida para el código y evita las fechas personales o los historiales de edición, que quedan obsoletos rápidamente.

Ejemplo de encabezado de un archivo Python

Este script autocontenido muestra un encabezado breve con una línea shebang, un docstring del módulo y comentarios con detalles que quien lo mantenga debe sustituir por información específica del proyecto. La descripción y los comentarios son documentación; la función y la protección main son código Python ejecutable.

#!/usr/bin/env python3
"""Print a short status message for a sample command-line tool."""

# Maintainer: Replace with a team or owner.
# Usage: python status_report.py
# License: Replace with the project's actual license.

def main():
    print("Report ready")


if __name__ == "__main__":
    main()

Adapta los comentarios al archivo: añade notas sobre dependencias o versiones de Python solo cuando afecten a la configuración o al uso. El ejemplo no tiene dependencias externas, así que no necesita una lista de importaciones. La línea shebang es relevante cuando el archivo se ejecuta como programa en un sistema que la reconoce; al invocarlo con python status_report.py, se usa el intérprete indicado en ese comando.

Buenas prácticas para los encabezados de archivos Python

• Mantén el encabezado breve y céntrate en los datos que ayuden a usar o mantener el archivo.
• Sigue el formato existente del proyecto para que sea fácil revisar archivos relacionados.
• Coloca el docstring del módulo antes de las importaciones y usa comentarios para las notas que no formen parte de la documentación del módulo.
• Antes de añadir datos sobre el intérprete, las dependencias o la licencia, compruébalos en la configuración actual del proyecto.
• Actualiza o elimina las notas cuando dejen de ser correctas; omite campos como el autor o la fecha de modificación si el proyecto ya los registra en otro lugar.

Un encabezado común útil es el más breve que proporciona al siguiente desarrollador el contexto que necesita. Trátalo como documentación que evoluciona y deja que las convenciones del proyecto determinen qué datos opcionales corresponden a cada archivo.