Was ist das übliche Header-Format von Python-Dateien?

In einem Dokument über Python-Codierungsrichtlinien bin ich auf das folgende Header-Format für Python-Quelldateien gestoßen:

#!/usr/bin/env python

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

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

Ist dies das Standardformat für Header in der Python-Welt? Welche anderen Felder / Informationen kann ich in die Kopfzeile einfügen? Python-Gurus teilen Ihre Richtlinien für gute Python-Quell-Header :-)

Es sind alle Metadaten für das FoobarModul.

Das erste ist das docstringdes Moduls, das bereits in Peters Antwort erklärt wurde .

Wie organisiere ich meine Module (Quelldateien)? (Archiv)

Die erste Zeile jeder Datei sollte sein #!/usr/bin/env python. Dies ermöglicht es, die Datei als Skript auszuführen, das den Interpreter implizit aufruft, z. B. in einem CGI-Kontext.

Als nächstes sollte die Dokumentzeichenfolge mit einer Beschreibung folgen. Wenn die Beschreibung lang ist, sollte die erste Zeile eine kurze Zusammenfassung sein, die für sich genommen sinnvoll ist und durch eine neue Zeile vom Rest getrennt ist.

Der gesamte Code, einschließlich der Importanweisungen, sollte der Dokumentzeichenfolge folgen. Andernfalls wird die Dokumentzeichenfolge vom Interpreter nicht erkannt, und Sie haben in interaktiven Sitzungen (dh bis obj.__doc__) oder beim Generieren von Dokumentation mit automatisierten Tools keinen Zugriff darauf .

Importieren Sie zuerst integrierte Module, gefolgt von Modulen von Drittanbietern, gefolgt von Änderungen am Pfad und Ihren eigenen Modulen. Insbesondere Änderungen am Pfad und an den Namen Ihrer Module ändern sich wahrscheinlich schnell: Wenn Sie sie an einem Ort aufbewahren, sind sie leichter zu finden.

Als nächstes sollten Informationen zur Urheberschaft folgen. Diese Informationen sollten diesem Format folgen:

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

Der Status sollte normalerweise "Prototyp", "Entwicklung" oder "Produktion" sein. __maintainer__sollte die Person sein, die Fehler behebt und Verbesserungen vornimmt, wenn sie importiert wird. __credits__unterscheidet sich davon __author__darin, dass __credits__Personen eingeschlossen sind, die Fehlerbehebungen gemeldet, Vorschläge gemacht usw. haben, den Code jedoch nicht tatsächlich geschrieben haben.

Hier haben Sie weitere Informationen, die Auflistung __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__und __version__als anerkannte Metadaten.

Ich bevorzuge nachdrücklich minimale Datei-Header, womit ich nur meine:

• Der Hashbang ( #!Zeile), wenn dies ein ausführbares Skript ist
• Modul docstring
• Importe, standardisiert gruppiert, zB:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

dh. drei Gruppen von Importen mit einer einzigen Leerzeile dazwischen. Innerhalb jeder Gruppe werden Importe sortiert. Die letzte Gruppe, Importe aus lokaler Quelle, können entweder absolute Importe wie gezeigt oder explizite relative Importe sein.

Alles andere ist Zeitverschwendung, visueller Raum und aktiv irreführend.

Wenn Sie rechtliche Hinweise oder Lizenzinformationen haben, werden diese in einer separaten Datei gespeichert. Es muss nicht jede Quellcodedatei infizieren. Ihr Urheberrecht sollte ein Teil davon sein. Die Leute sollten es in Ihrer LICENSEDatei finden können, nicht in zufälligem Quellcode.

Metadaten wie Urheberschaft und Datum werden bereits von Ihrer Quellcodeverwaltung verwaltet. Es ist nicht erforderlich, der Datei selbst eine weniger detaillierte, fehlerhafte und veraltete Version derselben Informationen hinzuzufügen.

Ich glaube nicht, dass es andere Daten gibt, die jeder in all seine Quelldateien einfügen muss. Möglicherweise haben Sie eine bestimmte Anforderung, aber solche Dinge gelten per Definition nur für Sie. Sie haben keinen Platz in "allgemeinen Überschriften, die für alle empfohlen werden".

Die obigen Antworten sind wirklich vollständig, aber wenn Sie möchten, dass ein schneller und schmutziger Header kopiert und eingefügt wird, verwenden Sie Folgendes:

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

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

Warum das so ist:

• Die erste Zeile ist für * nix Benutzer. Der Python-Interpreter wird im Benutzerpfad ausgewählt, daher wird automatisch der vom Benutzer bevorzugte Interpreter ausgewählt.
• Die zweite ist die Dateicodierung. Heutzutage muss jeder Datei eine Codierung zugeordnet sein. UTF-8 funktioniert überall. Nur ältere Projekte würden eine andere Codierung verwenden.
• Und eine sehr einfache Dokumentation. Es kann mehrere Zeilen füllen.

Siehe auch: https://www.python.org/dev/peps/pep-0263/

Wenn Sie nur eine Klasse in jede Datei schreiben, benötigen Sie nicht einmal die Dokumentation (sie würde in das Klassendokument aufgenommen).

Siehe auch PEP 263, wenn Sie einen Nicht-ASCII-Zeichensatz verwenden

Abstrakt

In diesem PEP wird vorgeschlagen, eine Syntax einzuführen, um die Codierung einer Python-Quelldatei zu deklarieren. Die Codierungsinformationen werden dann vom Python-Parser verwendet, um die Datei unter Verwendung der angegebenen Codierung zu interpretieren. Dies verbessert insbesondere die Interpretation von Unicode-Literalen im Quellcode und ermöglicht das Schreiben von Unicode-Literalen mit z. B. UTF-8 direkt in einem Unicode-fähigen Editor.

Problem

In Python 2.1 können Unicode-Literale nur mit der Latin-1-basierten Codierung "Unicode-Escape" geschrieben werden. Dies macht die Programmierumgebung für Python-Benutzer, die in Nicht-Latin-1-Regionen wie vielen asiatischen Ländern leben und arbeiten, eher unfreundlich. Programmierer können ihre 8-Bit-Zeichenfolgen mit der bevorzugten Codierung schreiben, sind jedoch an die "Unicode-Escape" -Codierung für Unicode-Literale gebunden.

Vorgeschlagene Lösung

Ich schlage vor, die Python-Quellcode-Codierung für jede Quelldatei sichtbar und änderbar zu machen, indem ein spezieller Kommentar oben in der Datei verwendet wird, um die Codierung zu deklarieren.

Um Python auf diese Codierungsdeklaration aufmerksam zu machen, sind einige Konzeptänderungen in Bezug auf den Umgang mit Python-Quellcodedaten erforderlich.

Codierung definieren

Python verwendet standardmäßig ASCII als Standardcodierung, wenn keine anderen Codierungshinweise angegeben werden.

Um eine Quellcode-Codierung zu definieren, muss ein magischer Kommentar entweder als erste oder zweite Zeile in der Datei in die Quelldateien eingefügt werden, z.

      # coding=<encoding name>

oder (unter Verwendung von Formaten, die von bekannten Redakteuren erkannt werden)

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

oder

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

...