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


508

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 :-)


Aquí hay un buen lugar para comenzar: PEP 257 , que habla sobre Docstrings y enlaces a varios otros documentos relevantes.
Peter

41
Quizás una guía útil para quienes leen las diferentes respuestas a esta pregunta es considerar para qué fines esperan que se usen estos encabezados de archivo. Si tiene un caso de uso concreto (por ejemplo, mi abogado dice que los casos judiciales se pierden porque los desarrolladores no pudieron incluir información de copyright en cada archivo). Luego agregue y mantenga la información que necesita para ese caso de uso. De lo contrario, solo estás disfrutando de tu fetiche con TOC.
Jonathan Hartley

jaja genial @JonathanHartley! Para mis propios proyectos, como tú lo pones "me complazco con mi fetiche del TOC". jajajaja stackoverflow.com/a/51914806/1896134
JayRizzo

Respuestas:


577

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.


77
¿Se puede automatizar de alguna manera la creación de la información del encabezado para nuevos archivos?
Hauke

184
Creo que todos estos metadatos después de las importaciones son una mala idea. Las partes de estos metadatos que se aplican a un solo archivo (por ejemplo, autor, fecha) ya son rastreados por el control de origen. Poner una copia errónea y desactualizada de la misma información en el archivo me parece incorrecto. Las partes que se aplican a todo el proyecto (por ejemplo, licencia, versiones) parecen ubicarse mejor a nivel de proyecto, en un archivo propio, en lugar de en cada archivo de código fuente.
Jonathan Hartley

28
Estoy totalmente de acuerdo con Jonathan Hartley. La siguiente persona que herede el código tiene tres opciones: 1) actualizarlo cada vez que edite el código 2) dejarlo solo, en cuyo caso será inexacto 3) eliminarlo todo. La opción 1 es una pérdida de tiempo, especialmente porque no tienen absolutamente ninguna confianza en que los metadatos estaban actualizados cuando los recibieron. Las opciones 2 y 3 significan que perdió su tiempo en ponerlo allí en primer lugar. Solución: ahorre tiempo a todos y no lo ponga allí.
spookylukey

77
No hay razón para que la mayoría de los archivos Python tengan una línea shebang.
Mike Graham

15
Según PEP 8, __version__debe seguir directamente la cadena de documentación principal, con una línea en blanco antes y después. Además, es una buena práctica definir su juego de caracteres inmediatamente debajo del shebang -# -*- coding: utf-8 -*-
Dave Lasley

179

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".


23
No podría estar más de acuerdo: es un pecado replicar el código en varios lugares, entonces, ¿por qué hacer lo mismo con la información de un encabezado? Póngalo en un solo lugar (raíz del proyecto) y evite la molestia de mantener dicha información en muchos, muchos archivos.
Graeme

13
Si bien estoy de acuerdo en que el control de la fuente tiende a proporcionar información de autoría más válida, a veces los autores solo distribuyen la fuente sin dar acceso al repositorio, o tal vez esa es la forma en que funciona la distribución, por ejemplo: instalación centralizada desde pypi. Por lo tanto, incrustar información de autoría como un encabezado de módulo sigue siendo beneficioso.
cochecito

66
Hola cochecito Tengo problemas para imaginar un caso de uso en el que eso sea realmente útil. Me imagino a alguien que quiera conocer la información de autoría del proyecto en su conjunto, y puede obtener valor de una lista de los principales contribuyentes en un solo lugar central, tal vez el archivo README o los documentos del proyecto. Pero quién (a) querría saber la autoría de los archivos individuales , y (b) no tendría acceso al repositorio fuente, y (c) no le importaría que nunca haya una manera de saber si la información es incorrecta o ¿fuera de plazo?
Jonathan Hartley

12
Muchas licencias requieren que incluya la plantilla de licencia en cada archivo por una muy buena razón. Si alguien toma un archivo o dos y los redistribuye sin la licencia, las personas que lo reciben no tienen idea de qué licencia tiene, y tendrán que rastrearlo (suponiendo que sean de buena fe).
nyuszika7h

3
Sin embargo, muchos módulos (scipy, numpy, matplotlib) tienen __version__metadatos, y creo que es bueno tenerlos , ya que deberían ser accesibles para los programas y verificar rápidamente en el intérprete interactivo. Sin embargo, la autoría y la información legal pertenecen a un archivo diferente. A menos que tenga un caso de uso paraif 'Rob' in __author__:
endolith

34

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).


55
> "Hoy en día cada archivo debe tener una codificación asociada". Esto parece engañoso. utf8 es la codificación predeterminada, por lo que está perfectamente bien no especificarla.
Jonathan Hartley

23

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> :

...


15
Vale la pena señalar que desde Python 3, el conjunto de caracteres predeterminado es UTF-8.
nyuszika7h
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.