Intestazione di file Python

L’intestazione di un file Python è documentazione facoltativa collocata all’inizio del file sorgente. Un progetto può adottare un formato condiviso per spiegare lo scopo e l’uso previsto di uno script, i requisiti e la licenza; Python non impone un’intestazione specifica. Includi solo le informazioni che aiutano a capire o a eseguire il file e segui le convenzioni del progetto.

Perché usare un formato comune per le intestazioni in Python

Un’intestazione coerente offre ai lettori un contesto utile prima che esaminino l’implementazione. Può indicare lo scopo dello script, chi lo mantiene, come eseguirlo e gli eventuali requisiti importanti relativi all’ambiente di esecuzione o alle dipendenze. Un avviso di licenza può inoltre chiarire come usare il codice, purché corrisponda alla licenza effettiva del progetto.

Il formato è una convenzione del team, non una funzionalità del linguaggio Python. Per un piccolo script occasionale può bastare una breve descrizione del modulo; uno strumento da riga di comando distribuito, invece, può trarre vantaggio da indicazioni sull’uso e sulle dipendenze. La coerenza è utile quando più file appartengono allo stesso repository, ma copiare campi non pertinenti aggiunge disordine e rischia di lasciare informazioni obsolete.

Componenti di un’intestazione di file Python

Scegli i componenti in base a come il file viene eseguito e mantenuto. Un’intestazione combina spesso metadati per l’interprete, una docstring del modulo e commenti rivolti ai lettori.

Riga shebang

Una riga shebang è un marcatore sulla prima riga, per esempio #!/usr/bin/env python3. Nei sistemi che la riconoscono, eseguire tramite il suo percorso uno script contrassegnato come eseguibile usa l’interprete selezionato da env. È utile per gli script da riga di comando sui sistemi Unix-like, ma non serve quando si avvia un file con un comando come python script.py. Questa riga non installa Python né seleziona un ambiente per ogni possibile modalità di avvio del file.

Dichiarazione della codifica

Per impostazione predefinita, i file sorgente Python 3 usano UTF-8, quindi in genere non occorre dichiarare la codifica. Se, per compatibilità con uno strumento o un ambiente specifico, un file sorgente usa un’altra codifica, Python riconosce una dichiarazione come # -*- coding: latin-1 -*- sulla prima o sulla seconda riga. La dichiarazione deve corrispondere alla codifica effettiva del file: non è un indicatore generico che rende leggibile qualsiasi testo.

Docstring del modulo e commenti

Una docstring del modulo è un literal string all’inizio del modulo, dopo un’eventuale riga shebang o un commento sulla codifica. Descrive il modulo ed è disponibile tramite __doc__. Usala per indicare brevemente lo scopo e fornire informazioni utili a livello di modulo. I commenti ordinari possono contenere note sulla manutenzione, sull’uso, sulle dipendenze, sulla versione o sulla licenza; Python non interpreta automaticamente questi commenti come metadati.

Gli import vanno dopo la docstring del modulo e prima delle altre istruzioni eseguibili. Se sono necessari, una convenzione comune prevede di raggruppare prima gli import della libreria standard, poi i pacchetti di terze parti e infine gli import locali del progetto, separando i gruppi con una riga vuota.

Quando sono rilevanti, l’intestazione può indicare come eseguire uno script, quali pacchetti servono o quale versione minima di Python è richiesta. Mantieni i requisiti in linea con la configurazione effettiva del progetto. Aggiungi un avviso di licenza solo se corrisponde a quella scelta per il codice ed evita date personali o cronologie delle modifiche, che diventano rapidamente inesatte.

Esempio di intestazione per un file Python

Questo script autonomo mostra un’intestazione concisa con una riga shebang, una docstring del modulo e commenti che chi mantiene il file dovrebbe sostituire con informazioni specifiche del progetto. La descrizione e i commenti sono documentazione; la funzione e il controllo main sono Python eseguibile.

#!/usr/bin/env python3
"""Print a short status message for a sample command-line tool."""

# Maintainer: Replace with a team or owner.
# Usage: python status_report.py
# License: Replace with the project's actual license.

def main():
    print("Report ready")


if __name__ == "__main__":
    main()

Adatta i commenti al file: aggiungi note sulle dipendenze o sulla versione di Python solo se incidono sulla configurazione o sull’uso. L’esempio non ha dipendenze esterne, quindi non richiede un elenco di import. La riga shebang è utile quando il file viene avviato come eseguibile su un sistema che la riconosce; se lo esegui con python status_report.py, viene usato l’interprete indicato in quel comando.

Buone pratiche per le intestazioni dei file Python

• Mantieni l’intestazione breve e concentrata sulle informazioni che aiutano a usare o mantenere il file.
• Segui il formato già adottato dal progetto, così i file correlati sono facili da consultare.
• Inserisci la docstring del modulo prima degli import e usa i commenti per le note che non fanno parte della documentazione del modulo.
• Prima di aggiungere informazioni, verifica i dettagli sull’interprete, sulle dipendenze e sulla licenza confrontandoli con la configurazione aggiornata del progetto.
• Aggiorna o rimuovi le note quando non sono più corrette; ometti campi come l’autore o la data di modifica se il progetto li registra già altrove.

Un’intestazione comune utile è la più breve che fornisce al prossimo sviluppatore il contesto necessario. Considerala documentazione da mantenere aggiornata e lascia che siano le convenzioni del progetto a determinare quali dettagli facoltativi includere in ciascun file.