¿Cuál es el formato de encabezado común de los archivos Python?
Encontré el siguiente formato de encabezado para archivos fuente de Python en un documento sobre 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 Python? ¿Qué otros campos/información puedo poner en el encabezado? Los gurús de Python comparten sus pautas para buenos encabezados fuente de Python :-)
Todos son 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.Lo siguiente debería ser la cadena de documentación 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, el intérprete no reconocerá la cadena de documentación y usted no tendrá acceso a ella en sesiones interactivas (es decir, a través de
obj.__doc__) o cuando genere 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 hace que sean más fáciles de encontrar.
Lo siguiente debería 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__ = "[email protected]" __status__ = "Production"El estado normalmente debe ser uno de "Prototipo", "Desarrollo" o "Producción".
__maintainer__debe ser la persona que corregirá los errores y realizará mejoras si se importa.__credits__se diferencia de__author__en que__credits__incluye personas que informaron correcciones de errores, hicieron sugerencias, etc. pero en realidad no escribieron el código.
Aquí tenéis más información, enumerando __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__y __version__como metadatos reconocidos.
Prefiero firmemente los encabezados de archivo mínimos, con lo que me refiero simplemente a:
#!/usr/bin/env python # [1]
"""\
This script foos the given bars [2]
Usage: myscript.py BAR1 BAR2
"""
import os # standard library, [3]
import sys
import requests # 3rd party packages
import mypackage # local source
[1]El hashbang si, y sólo si, este archivo debería poder ejecutarse directamente, es decir, ejecutarse comomyscript.pyomyscripto tal vez inclusopython myscript.py. (El hashbang no se usa en el último caso, pero proporcionarlo les da a los usuarios la opción de ejecutarlo de cualquier manera). El hashbang no debe incluirse si el archivo es un módulo, destinado solo a ser importado por otros archivos de Python.[2]Cadena de documentación del módulo[3]Importaciones, agrupadas de forma estándar, es decir. tres grupos de importaciones, con una sola línea en blanco entre ellos. Dentro de cada grupo, las importaciones están clasificadas. El grupo final, las importaciones de fuente local, pueden ser importaciones absolutas, como se muestra, o importaciones relativas explícitas.
Todo lo demás es una pérdida de tiempo, tanto para el autor como para los mantenedores posteriores. Desperdicia el valioso espacio visual en la parte superior del archivo con información que se puede rastrear mejor en otros lugares, y es fácil quedar obsoleto y volverse activamente engañoso.
Si tiene exenciones de responsabilidad legales o información de licencia, se guarda en un archivo separado. No es necesario infectar todos los archivos de código fuente. Tus derechos de autor deberían ser parte de esto. La gente debería poder encontrarlo en su LICENSEarchivo, no en un código fuente aleatorio.
Su control de fuente ya mantiene 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 ningún otro dato que todos deban incluir en todos sus archivos fuente. Es posible que tenga algún requisito particular para hacerlo, pero esas cosas se aplican, por definición, sólo a usted. No tienen cabida en los “encabezados generales recomendados para todos”.
Las respuestas anteriores son realmente completas, pero si desea copiar y pegar un encabezado rápido y sencillo, 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. 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 todo 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 sencilla. Puede llenar varias líneas.
Ver también: https://www.python.org/dev/peps/pep-0263/
Si simplemente 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 que no es ASCII.
Abstracto
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 proporcionada. En particular, esto mejora la interpretación de los literales Unicode en el código fuente y hace posible escribir literales Unicode utilizando, por ejemplo, UTF-8 directamente en un editor compatible con Unicode.
Problema
En Python 2.1, los literales Unicode sólo 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 lugares 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 "unicode-escape" para los literales Unicode.
Solución propuesta
Propongo hacer que la codificación del código fuente de Python sea visible y modificable según el archivo fuente mediante el uso de un comentario especial en la parte superior del archivo para declarar la codificación.
Para que Python sea consciente de esta declaración de codificación, se necesitan una serie de cambios conceptuales con respecto al manejo de los datos del código fuente de Python.
Definiendo la codificación
Python utilizará de forma predeterminada ASCII como codificación estándar si no se dan 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, ya sea como primera o segunda línea del archivo, como por ejemplo:
# 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> :...
Lo que uso en algún proyecto es esta línea en la primera línea para máquinas Linux:
# -*- coding: utf-8 -*-
Como crédito de autor y DOC, me gustan las cadenas simples en varias líneas. Aquí un ejemplo de ejemplo de cadenas de documentos Python estilo Google
# -*- coding: utf-8 -*-
"""Example Google style docstrings.
This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.
Example:
Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
Attributes:
module_level_variable1 (int): Module level variables may be documented in
either the ``Attributes`` section of the module docstring, or in an
inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent
with it.
Todo:
* For module TODOs
* You have to also use ``sphinx.ext.todo`` extension
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
"""
También puede ser bueno agregar:
"""
@Author: ...
@Date: ....
@Credit: ...
@Links: ...
"""
Formatos adicionales
Marcado de metainformación | guía de desarrollo
"""
:mod:`parrot` -- Dead parrot access =================================== .. module:: parrot :platform: Unix, Windows :synopsis: Analyze and reanimate dead parrots. .. moduleauthor:: Eric Cleese <[email protected]> .. moduleauthor:: John Idle <[email protected]> """/encabezado-común-python
#!/usr/bin/env python3 Line 1 # -*- coding: utf-8 -*- Line 2 #---------------------------------------------------------------------------- # Created By : name_of_the_creator Line 3 # Created Date: date/month/time ..etc # version ='1.0' # ---------------------------------------------------------------------------
También informo de manera similar a otras respuestas.
__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"
