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

formas de leer un archivo en python

Question

Encontré el siguiente formato de encabezado para los archivos fuente de Python en un documento sobre las directrices 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 Python? ¿Qué otros campos / información puedo poner en el encabezado? Los gurús de Python comparten sus pautas para buenos encabezados de fuente de Python :-)

Answer 1

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

• El hashbang ( #! Line) si este es un script ejecutable
• Módulo docstring
• Importaciones, agrupadas como se describe en la respuesta del viajero .

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, se guarda en un archivo separado. No necesita infectar cada archivo de código fuente. Su copyright debe ser parte de esto. La gente debería poder encontrarlo en su archivo de LICENSE , no en un código fuente aleatorio.

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

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

Answer 2

Las respuestas anteriores están realmente completas, pero si quieres un encabezado rápido y sucio para copiar y pegar, usa 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. Elegirá el intérprete de Python en la ruta del usuario, por lo que elegirá automáticamente el intérprete preferido del 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 utilizarían otra codificación.
• Y una documentación muy sencilla. Puede rellenar varias líneas.

Véase 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).

Answer 3

También vea PEP 263 si está usando un conjunto de caracteres que no sea ASCII

Resumen

Este PEP propone introducir una sintaxis para declarar la codificación de un archivo fuente de Python. 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 de Unicode en el código fuente y hace posible escribir literales de Unicode utilizando, por ejemplo, UTF-8 directamente en un editor con conocimiento de Unicode.

Problema

En Python 2.1, los literales de Unicode solo se pueden escribir utilizando 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 locales no latinos-1 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 "escape-unicode" para los literales de Unicode.

Solución propuesta

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

Para que Python esté al tanto 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 se establecerá de forma predeterminada en 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 de origen como primera o segunda línea del archivo, como por ejemplo:

      # coding=<encoding name>

o (utilizando formatos reconocidos por editores populares)

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

o

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

...

Answer 4

Todos sus metadatos para el módulo de Foobar .

La primera es la docstring de documentación del 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 que sea posible ejecutar el archivo como un script que invoca al intérprete implícitamente, por ejemplo, en un contexto CGI.

El siguiente debe ser el docstring con una descripción. Si la descripción es larga, la primera línea debe ser un breve resumen que tenga sentido por sí solo, 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 documentos 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.

Primero, importe los módulos incorporados, seguidos de los módulos de terceros, y luego los cambios 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 hace que sean más fáciles de encontrar.

A continuación debe ser 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__ = "[email protected]"
__status__ = "Production"

El estado debería ser típicamente uno de "Prototipo", "Desarrollo" o "Producción". __maintainer__ debe ser la persona que solucionará los errores y realizará mejoras si se importa. __credits__ difiere de __author__ en que __credits__ incluye a las personas que informaron correcciones de errores, hicieron sugerencias, etc. pero en realidad no escribieron el código.

Here tiene más información, listando __author__ , __authors__ , __contact__ , __copyright__ , __license__ , __deprecated__ , __date__ y __version__ como metadatos reconocidos.