Qual è il formato di intestazione comune dei file Python?

Mi sono imbattuto nel seguente formato di intestazione per i file sorgente Python in un documento sulle linee guida per la codifica Python:

#!/usr/bin/env python

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

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

È questo il formato standard delle intestazioni nel mondo Python? Quali altri campi / informazioni posso inserire nell'intestazione? I guru di Python condividono le tue linee guida per le buone intestazioni dei sorgenti di Python :-)

Sono tutti metadati per il Foobarmodulo.

Il primo è il docstringmodulo, che è già spiegato nella risposta di Peter .

Come organizzo i miei moduli (file sorgente)? (Archivio)

La prima riga di ogni file dovrebbe essere #!/usr/bin/env python. Ciò consente di eseguire il file come script invocando implicitamente l'interprete, ad esempio in un contesto CGI.

Il prossimo dovrebbe essere il docstring con una descrizione. Se la descrizione è lunga, la prima riga dovrebbe essere un breve riassunto che abbia un senso da sola, separata dal resto da una nuova riga.

Tutto il codice, comprese le dichiarazioni di importazione, dovrebbe seguire la documentazione. Altrimenti, il docstring non verrà riconosciuto dall'interprete e non avrai accesso ad esso in sessioni interattive (cioè attraverso obj.__doc__) o durante la generazione di documentazione con strumenti automatizzati.

Importa prima i moduli integrati, seguiti dai moduli di terze parti, seguiti da eventuali modifiche al percorso e ai tuoi moduli. In particolare, è probabile che le aggiunte al percorso e ai nomi dei tuoi moduli cambino rapidamente: tenerli in un posto li rende più facili da trovare.

Il prossimo dovrebbe essere informazioni sulla paternità. Queste informazioni dovrebbero seguire questo 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"

Lo stato dovrebbe in genere essere "Prototipo", "Sviluppo" o "Produzione". __maintainer__dovrebbe essere la persona che risolverà i bug e apporterà miglioramenti se importato. __credits__differisce da __author__quello che __credits__include le persone che hanno segnalato correzioni di bug, suggerimenti, ecc. ma che in realtà non hanno scritto il codice.

Qui si hanno più informazioni, elencando __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__e __version__metadati come riconosciuto.

Prediligo fortemente le intestazioni di file minime, intendo semplicemente:

• L'hashbang ( #!linea) se questo è uno script eseguibile
• Docstring del modulo
• Importazioni, raggruppate in modo standard, ad esempio:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

vale a dire. tre gruppi di importazioni, con un'unica riga vuota tra di loro. All'interno di ciascun gruppo, le importazioni sono ordinate. Il gruppo finale, le importazioni da fonti locali, possono essere importazioni assolute come mostrato o importazioni relative esplicite.

Tutto il resto è una perdita di tempo, spazio visivo ed è attivamente fuorviante.

Se hai dichiarazioni di non responsabilità legali o informazioni sulla licenza, queste vanno in un file separato. Non è necessario infettare tutti i file di codice sorgente. Il tuo copyright dovrebbe far parte di questo. Le persone dovrebbero essere in grado di trovarlo nel tuo LICENSEfile, non nel codice sorgente casuale.

Metadati come la paternità e le date sono già gestiti dal controllo del codice sorgente. Non è necessario aggiungere una versione meno dettagliata, errata e non aggiornata delle stesse informazioni nel file stesso.

Non credo ci siano altri dati che tutti devono inserire in tutti i loro file di origine. Potresti avere dei requisiti particolari per farlo, ma tali cose si applicano, per definizione, solo a te. Non hanno posto in "intestazioni generali consigliate a tutti".

Le risposte sopra sono davvero complete, ma se vuoi copiare e incollare un'intestazione veloce e sporca, usa questo:

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

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

Perché questo è buono:

• La prima riga è per gli utenti * nix. Sceglierà l'interprete Python nel percorso dell'utente, quindi sceglierà automaticamente l'interprete preferito dall'utente.
• Il secondo è la codifica del file. Al giorno d'oggi ogni file deve avere una codifica associata. UTF-8 funzionerà ovunque. Solo i progetti legacy utilizzerebbero altre codifiche.
• E una documentazione molto semplice. Può riempire più righe.

Vedi anche: https://www.python.org/dev/peps/pep-0263/

Se scrivi semplicemente una classe in ciascun file, non hai nemmeno bisogno della documentazione (andrebbe all'interno del documento di classe).

Vedi anche PEP 263 se stai usando un set di caratteri non ASCII

Astratto

Questo PEP propone di introdurre una sintassi per dichiarare la codifica di un file sorgente Python. Le informazioni di codifica vengono quindi utilizzate dal parser Python per interpretare il file utilizzando la codifica fornita. In particolare, ciò migliora l'interpretazione dei letterali Unicode nel codice sorgente e consente di scrivere letterali Unicode usando ad esempio UTF-8 direttamente in un editor compatibile con Unicode.

Problema

In Python 2.1, i letterali Unicode possono essere scritti solo usando la codifica "unicode-escape" basata su Latin-1. Questo rende l'ambiente di programmazione piuttosto ostile agli utenti di Python che vivono e lavorano in locali non latini-1 come molti dei paesi asiatici. I programmatori possono scrivere le loro stringhe a 8 bit utilizzando la codifica preferita, ma sono associati alla codifica "unicode-escape" per i letterali Unicode.

La soluzione proposta

Propongo di rendere il codice sorgente Python codificante sia visibile che modificabile in base al file sorgente utilizzando un commento speciale nella parte superiore del file per dichiarare la codifica.

Per rendere Python consapevole di questa dichiarazione di codifica sono necessarie alcune modifiche al concetto riguardo alla gestione dei dati del codice sorgente di Python.

Definire la codifica

Python verrà automaticamente impostato su ASCII come codifica standard se non vengono forniti altri suggerimenti per la codifica.

Per definire una codifica del codice sorgente, un commento magico deve essere inserito nei file sorgente come prima o seconda riga nel file, ad esempio:

      # coding=<encoding name>

o (utilizzando formati riconosciuti da editor popolari)

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

o

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

...