¿Cuál es el formato de encabezado común de los archivos Python?

Encontré el siguiente formato de encabezado para los archivos fuente de Python en un documento sobre las pautas de codificación de Python:

#!/usr/bin/env python

"""Foobar.py: Description of what foobar does."""

__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

¿Es este el formato estándar de encabezados en el mundo de Python? ¿Qué otros campos / información puedo poner en el encabezado? Los gurús de Python comparten sus pautas para buenos encabezados de origen de Python :-)

Todos sus metadatos para el Foobarmódulo.

El primero es el docstringdel módulo, que ya se explica en la respuesta de Peter .

¿Cómo organizo mis módulos (archivos fuente)? (Archivo)

La primera línea de cada archivo debe ser #!/usr/bin/env python. Esto hace posible ejecutar el archivo como un script que invoca al intérprete implícitamente, por ejemplo, en un contexto CGI.

El siguiente debería ser la cadena de documentos con una descripción. Si la descripción es larga, la primera línea debe ser un breve resumen que tenga sentido por sí mismo, separado del resto por una nueva línea.

Todo el código, incluidas las declaraciones de importación, debe seguir la cadena de documentación. De lo contrario, la cadena de documentación no será reconocida por el intérprete y no tendrá acceso a ella en sesiones interactivas (es decir, a través de obj.__doc__) o al generar documentación con herramientas automatizadas.

Importe primero los módulos integrados, seguidos de los módulos de terceros, seguidos de cualquier cambio en la ruta y sus propios módulos. Especialmente, es probable que las adiciones a la ruta y los nombres de sus módulos cambien rápidamente: mantenerlos en un solo lugar los hace más fáciles de encontrar.

Lo siguiente debe ser la información de autoría. Esta información debe seguir este formato:

__author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell"
__copyright__ = "Copyright 2007, The Cogent Project"
__credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley",
                    "Matthew Wakefield"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Rob Knight"
__email__ = "rob@spot.colorado.edu"
__status__ = "Production"

El estado normalmente debe ser uno de "Prototipo", "Desarrollo" o "Producción". __maintainer__debería ser la persona que reparará los errores y hará mejoras si se importan. __credits__difiere __author__en que __credits__incluye a las personas que informaron la corrección de errores, hicieron sugerencias, etc., pero en realidad no escribieron el código.

Aquí tienes más información, lista __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__y __version__los metadatos como se reconoce.

Estoy a favor de los encabezados de archivos mínimos, con lo que quiero decir solo

• El hashbang ( #!línea) si este es un script ejecutable
• Módulo docstring
• Importaciones, agrupadas en la forma estándar, por ejemplo:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

es decir. tres grupos de importaciones, con una sola línea en blanco entre ellos. Dentro de cada grupo, las importaciones se ordenan. El grupo final, las importaciones de origen local, pueden ser importaciones absolutas como se muestra o importaciones relativas explícitas.

Todo lo demás es una pérdida de tiempo, espacio visual y es activamente engañoso.

Si tiene renuncias legales o información de licencia, va en un archivo separado. No necesita infectar todos los archivos de código fuente. Su copyright debe ser parte de esto. Las personas deberían poder encontrarlo en su LICENSEarchivo, no en código fuente aleatorio.

Los metadatos, como la autoría y las fechas, ya los mantiene su control de origen. No es necesario agregar una versión menos detallada, errónea y desactualizada de la misma información en el archivo mismo.

No creo que haya otros datos que todos necesiten poner en todos sus archivos fuente. Es posible que tenga algún requisito particular para hacerlo, pero tales cosas se aplican, por definición, solo a usted. No tienen lugar en "encabezados generales recomendados para todos".

Las respuestas anteriores son realmente completas, pero si desea un encabezado rápido y sucio para copiar y pegar, use esto:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""Module documentation goes here
   and here
   and ...
"""

Por qué esta es buena:

• La primera línea es para usuarios de * nix. Escogerá el intérprete de Python en la ruta del usuario, por lo que elegirá automáticamente el intérprete preferido por el usuario.
• El segundo es la codificación del archivo. Hoy en día cada archivo debe tener una codificación asociada. UTF-8 funcionará en todas partes. Solo los proyectos heredados usarían otra codificación.
• Y una documentación muy simple. Puede llenar múltiples líneas.

Ver también: https://www.python.org/dev/peps/pep-0263/

Si solo escribe una clase en cada archivo, ni siquiera necesita la documentación (iría dentro del documento de la clase).

Consulte también PEP 263 si está utilizando un conjunto de caracteres no ASCII

Resumen

Este PEP propone introducir una sintaxis para declarar la codificación de un archivo fuente de Python. Luego, el analizador de Python utiliza la información de codificación para interpretar el archivo utilizando la codificación dada. En particular, esto mejora la interpretación de los literales Unicode en el código fuente y hace posible escribir literales Unicode usando, por ejemplo, UTF-8 directamente en un editor compatible con Unicode.

Problema

En Python 2.1, los literales Unicode solo pueden escribirse usando la codificación basada en Latin-1 "unicode-escape". Esto hace que el entorno de programación sea bastante hostil para los usuarios de Python que viven y trabajan en entornos no latinos como muchos de los países asiáticos. Los programadores pueden escribir sus cadenas de 8 bits utilizando la codificación favorita, pero están vinculados a la codificación de "escape unicode" para los literales Unicode.

Solución propuesta

Propongo hacer que la codificación del código fuente de Python sea visible y modificable en función del archivo fuente utilizando un comentario especial en la parte superior del archivo para declarar la codificación.

Para que Python tenga conocimiento de esta declaración de codificación, se necesitan varios cambios de concepto con respecto al manejo de los datos del código fuente de Python.

Definiendo la codificación

Python establecerá de forma predeterminada ASCII como codificación estándar si no se proporcionan otras sugerencias de codificación.

Para definir una codificación de código fuente, se debe colocar un comentario mágico en los archivos fuente como primera o segunda línea en el archivo, como:

      # coding=<encoding name>

o (usando formatos reconocidos por editores populares)

      #!/usr/bin/python
      # -*- coding: <encoding name> -*-

o

      #!/usr/bin/python
      # vim: set fileencoding=<encoding name> :

...