it-swarm.com.de

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

In einem Dokument zu den Kodierungsrichtlinien für Python fand ich das folgende Headerformat für Python-Quelldateien:

#!/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 :-)

464
Ashwin Nanjappa

Alle Metadaten für das Foobar Modul.

Der erste ist der docstring des Moduls, der bereits in Peters Antwort erklärt ist.

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

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

Als nächstes sollte der Docstring mit einer Beschreibung kommen. Wenn die Beschreibung lang ist, sollte die erste Zeile sein Eine kurze Zusammenfassung, die für sich genommen Sinn macht und durch einen Zeilenumbruch 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 keinen Zugriff darauf in interaktiven Sitzungen (dh durch obj.__doc__) oder beim Generieren von Dokumentation mit automatisierten Tools.

Importieren Sie zuerst integrierte Module, gefolgt von Modulen von Drittanbietern, gefolgt von Änderungen am Pfad und Ihren eigenen Modulen. Insbesondere Hinzufügungen zum Pfad und die 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 angezeigt werden. Diese Informationen sollten in folgendem Format vorliegen:

__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 von __author__ darin, dass __credits__ Personen umfasst, die Fehlerbehebungen, Vorschläge usw. gemeldet haben, den Code jedoch nicht geschrieben haben.

Hier Sie haben weitere Informationen, die __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__ und __version__ als erkannte Metadaten.

524
Esteban Küber

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

  • Der Hashbang (#! Zeile), wenn dies ein ausführbares Skript ist
  • Moduldokumentation
  • Importe, wie üblich 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 einzelnen Leerzeile dazwischen. Innerhalb jeder Gruppe werden die Importe sortiert. Die letzte Gruppe, Importe aus lokaler Quelle, können entweder absolute Importe wie gezeigt oder explizite relative Importe sein.

Alles andere ist eine Verschwendung von Zeit und visuellem Raum und führt in die Irre.

Wenn Sie rechtliche Ausschlüsse oder Lizenzinformationen haben, werden diese in einer separaten Datei gespeichert. Es muss nicht jede Quellcodedatei infizieren. Ihr Urheberrecht sollte ein Teil davon sein. Die Benutzer sollten es in Ihrer LICENSE -Datei 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 müssen Sie dies in besonderer Weise tun, aber solche Dinge gelten per Definition nur für Sie. Sie haben keinen Platz in "allgemeinen Kopfzeilen, die für alle empfohlen werden".

159

Die obigen Antworten sind wirklich vollständig, aber wenn Sie eine schnelle und schmutzige Kopfzeile zum Kopieren und Einfügen benötigen, verwenden Sie diese:

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

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

Warum ist dies ein guter:

  • Die erste Zeile ist für * nix Benutzer. Es wählt den Interpreter Python im Benutzerpfad aus und wählt automatisch den vom Benutzer bevorzugten Interpreter aus.
  • Die zweite ist die Dateicodierung. Heutzutage muss jeder Datei eine Codierung zugeordnet sein. UTF-8 wird überall funktionieren. 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 werden).

28
neves

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

Abstrakt

Dieser PEP schlägt vor, eine Syntax einzuführen, um die Codierung einer Python-Quelldatei zu deklarieren. Die Codierungsinformationen werden dann vom Parser Python verwendet, um die Datei mit der angegebenen Codierung zu interpretieren. Dies verbessert insbesondere die Interpretation von Unicode-Literalen im Quellcode und ermöglicht das Schreiben von Unicode-Literalen unter Verwendung von z. 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-Gebieten wie vielen asiatischen Ländern leben und arbeiten, ziemlich 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 Sie einen speziellen Kommentar oben in der Datei verwenden, um die Codierung zu deklarieren.

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

Kodierung festlegen

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

      # coding=<encoding name>

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

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

oder

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

...

22
John La Rooy