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

508

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 :-)

Ashwin Nanjappa
quelle
Hier ist ein guter Anfang: PEP 257 , das sich mit Docstrings befasst und Links zu mehreren anderen relevanten Dokumenten enthält.
Peter
41
Eine nützliche Richtlinie für diejenigen, die die unterschiedlichen Antworten auf diese Frage lesen, ist möglicherweise die Überlegung, für welche Zwecke diese Dateikopfzeilen verwendet werden sollen. Wenn Sie einen konkreten Anwendungsfall haben (z. B. mein Anwalt sagt, dass Gerichtsverfahren verloren gehen, weil Entwickler nicht in jede einzelne Datei Copyright-Informationen eingefügt haben), fügen Sie die Informationen hinzu und pflegen Sie sie, die Sie für diesen Anwendungsfall benötigen. Ansonsten gönnen Sie sich einfach Ihren OCD-Fetisch.
Jonathan Hartley
haha toll @JonathanHartley! Für meine eigenen Projekte, wie Sie sagen "Ich gönne mir meinen OCD-Fetisch." hahaaha stackoverflow.com/a/51914806/1896134
JayRizzo

Antworten:

577

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__ = "[email protected]"
__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.

Esteban Küber
quelle
7
Kann die Erstellung der Header-Informationen für neue Dateien irgendwie automatisiert werden?
Hauke
184
Ich denke, all diese Metadaten nach dem Import sind eine schlechte Idee. Die Teile dieser Metadaten, die für eine einzelne Datei gelten (z. B. Autor, Datum), werden bereits von der Quellcodeverwaltung verfolgt. Das Einfügen einer fehlerhaften und veralteten Kopie derselben Informationen in die Datei selbst scheint mir falsch. Die Teile, die für das gesamte Projekt gelten (z. B. Lizenz, Versionierung), befinden sich auf Projektebene besser in einer eigenen Datei als in jeder Quellcodedatei.
Jonathan Hartley
28
Stimmen Sie Jonathan Hartley voll und ganz zu. Die nächste Person, die den Code erbt, hat drei Möglichkeiten: 1) Aktualisieren Sie alles jedes Mal, wenn sie den Code bearbeitet. 2) Lassen Sie ihn in Ruhe. In diesem Fall ist er ungenau. 3) Löschen Sie alles. Option 1 ist Zeitverschwendung, zumal sie absolut keine Gewissheit haben, dass die Metadaten zum Zeitpunkt ihres Eingangs auf dem neuesten Stand waren. Die Optionen 2 und 3 bedeuten, dass Ihre Zeit damit verschwendet wurde, sie dort zu platzieren. Lösung: Sparen Sie allen Zeit und legen Sie sie nicht dort ab.
Spookylukey
77
Es gibt keinen Grund für die meisten Python-Dateien, eine Shebang-Zeile zu haben.
Mike Graham
15
__version__Gemäß PEP 8 muss der Hauptdokumentationsstring direkt folgen, mit einer leeren Zeile davor und danach. Es ist auch empfehlenswert, Ihren Zeichensatz sofort unter dem Shebang zu definieren -# -*- coding: utf-8 -*-
Dave Lasley
179

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

Jonathan Hartley
quelle
23
Konnte nicht mehr zustimmen - es ist eine Sünde, Code an mehreren Stellen zu replizieren. Warum also dasselbe für eine Header-Information tun? Platzieren Sie es an einem einzigen Ort (Projektstamm) und vermeiden Sie den Aufwand, solche Informationen in vielen, vielen Dateien zu verwalten.
Graeme
13
Ich stimme zwar zu, dass die Quellcodeverwaltung tendenziell gültigere Informationen zur Urheberschaft liefert, aber manchmal verteilen Autoren die Quelle nur, ohne Zugriff auf das Repository zu gewähren, oder vielleicht funktioniert die Verteilung so, z. B.: Zentralisierte Installation von pypi. Das Einbetten von Autoreninformationen als Modulkopf ist daher weiterhin von Vorteil.
Kinderwagen
6
Hey Kinderwagen. Ich habe Probleme, mir einen Anwendungsfall vorzustellen, bei dem das tatsächlich nützlich ist. Ich kann mir vorstellen, dass jemand Informationen zur Urheberschaft für das gesamte Projekt erhalten möchte und dass er Wert aus einer Liste der wichtigsten Mitwirkenden an einem zentralen Ort ziehen kann, z. B. der README-Datei oder den Dokumenten des Projekts. Aber wer würde (a) die Urheberschaft einzelner Dateien wissen wollen und (b) keinen Zugriff auf das Quell-Repo haben und (c) sich nicht darum kümmern, dass es nie eine Möglichkeit gibt, festzustellen, ob die Informationen falsch sind oder veraltet?
Jonathan Hartley
12
Bei vielen Lizenzen müssen Sie aus gutem Grund das Lizenz-Boilerplate in jede Datei aufnehmen. Wenn jemand eine oder zwei Dateien nimmt und sie ohne die Lizenz weitergibt, haben die Personen, die sie erhalten, keine Ahnung, unter welcher Lizenz sie sich befinden, und müssen sie aufspüren (vorausgesetzt, sie sind in gutem Glauben).
Nyuszika7h
3
Viele Module (scipy, numpy, matplotlib) haben jedoch __version__Metadaten, und ich denke, das ist gut zu haben, da es für Programme zugänglich sein und schnell im interaktiven Interpreter einchecken sollte. Urheberschaft und rechtliche Informationen gehören jedoch in eine andere Datei. Es sei denn, Sie haben einen Anwendungsfall fürif 'Rob' in __author__:
Endolith
34

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).

neves
quelle
5
> "Heutzutage muss jeder Datei eine Codierung zugeordnet sein." Dies scheint irreführend. utf8 ist die Standardcodierung, daher ist es vollkommen in Ordnung, sie nicht anzugeben.
Jonathan Hartley
23

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> :

...

John La Rooy
quelle
15
Es ist erwähnenswert, dass seit Python 3 der Standardzeichensatz UTF-8 ist.
Nyuszika7h