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

Question

In einem Dokument über Python-Codierrichtlinien 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 Kopfzeilen in der Python-Welt? Welche anderen Felder/Informationen kann ich in den Header einfügen? Python-Gurus, teilen Sie Ihre Richtlinien für gute Python-Quelltext-Header :-)

Answer 1

Es sind alle Metadaten für die Foobar Modul.

Die erste ist die docstring des Moduls, die bereits in Petrus' Antwort .

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

Die erste Zeile einer jeden Datei sollte lauten #!/usr/bin/env python . Damit ist es möglich, die Datei als Skript auszuführen, das den Interpreter implizit aufruft, z.B. in einem CGI-Kontext.

Als nächstes sollte der Docstring mit einer Beschreibung folgen. Wenn die Beschreibung lang ist, sollte die erste Zeile eine kurze Zusammenfassung sein, die für sich genommen Sinn macht und durch einen Zeilenumbruch vom Rest getrennt ist.

Der gesamte Code, einschließlich der Importanweisungen, sollte dem Docstring folgen. Andernfalls wird der Docstring vom Interpreter nicht erkannt, und Sie können in interaktiven Sitzungen nicht darauf zugreifen (z. B. über obj.__doc__ ) oder bei der Erstellung von Dokumentation mit automatisierten Werkzeugen.

Importieren Sie zuerst die eingebauten Module, dann die Module von Drittanbietern und anschließend alle Änderungen am Pfad und Ihre eigenen Module. Vor allem Ergänzungen des Pfads und der Namen Ihrer Module werden sich wahrscheinlich schnell ändern: Wenn Sie sie an einem Ort aufbewahren, sind sie leichter zu finden.

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

__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 in der Regel einer der folgenden sein: "Prototyp", "Entwicklung" oder "Produktion". __maintainer__ sollte die Person sein, die Fehler behebt und Verbesserungen vornimmt, wenn sie importiert werden. __credits__ unterscheidet sich von __author__ in diesem __credits__ umfasst Personen, die Fehlerbehebungen gemeldet, Vorschläge gemacht usw. haben, aber nicht den eigentlichen Code geschrieben haben.

Hier Sie haben mehr Informationen, die Liste __author__ , __authors__ , __contact__ , __copyright__ , __license__ , __deprecated__ , __date__ y __version__ als anerkannte Metadaten.

Answer 2

Ich bin ein großer Befürworter von minimalen Dateikopfzeilen, d.h. nur:

• Das Rautenzeichen ( #! Zeile), wenn es sich um ein ausführbares Skript handelt
• Modul docstring

• Einfuhren, die standardmäßig gruppiert sind, z. B:

  import os # standard library import sys

  import requests # 3rd party packages

  from mypackage import ( # local source mymodule, myothermodule, )

d.h. drei Gruppen von Einfuhren, mit einer einzigen Leerzeile dazwischen. Innerhalb jeder Gruppe werden die Importe sortiert. Die letzte Gruppe, Importe aus lokaler Quelle, kann entweder absolute Importe sein, wie gezeigt, oder explizite relative Importe.

Alles andere ist eine Verschwendung von Zeit und visuellem Raum und ist aktiv irreführend.

Wenn Sie rechtliche Hinweise oder Informationen zur Lizenzierung haben, werden diese in einer separaten Datei gespeichert. Sie müssen nicht jede Quellcodedatei infizieren. Ihr Urheberrecht sollte ein Teil davon sein. Die Leute sollten in der Lage sein, es in Ihrer LICENSE Datei, nicht zufälliger Quellcode.

Metadaten wie Urheberschaft und Datum werden bereits von Ihrer Versionsverwaltung gepflegt. Es besteht keine Notwendigkeit, eine weniger detaillierte, fehlerhafte und veraltete Version der gleichen Informationen in die Datei selbst einzufügen.

Ich glaube nicht, dass es weitere Daten gibt, die jeder in seine Quelldateien aufnehmen muss. Sie haben vielleicht eine bestimmte Anforderung, aber solche Dinge gelten per Definition nur für Sie. Sie haben keinen Platz in den "allgemeinen, für alle empfohlenen Kopfzeilen".

Answer 3

Die obigen Antworten sind wirklich vollständig, aber wenn Sie eine schnelle und schmutzige Überschrift 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 dies ein gutes Beispiel ist:

• Die erste Zeile ist für *nix-Benutzer. Sie wählt den Python-Interpreter im Benutzerpfad aus, wählt also automatisch den vom Benutzer bevorzugten Interpreter.
• Der zweite Punkt ist die Dateikodierung. Heutzutage muss jede Datei mit einer Kodierung versehen sein. UTF-8 wird überall funktionieren. Nur ältere Projekte würden eine andere Kodierung verwenden.
• Und eine sehr einfache Dokumentation. Sie kann mehrere Zeilen füllen.

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

Wenn Sie nur eine Klasse in jede Datei schreiben, brauchen Sie nicht einmal die Dokumentation (sie würde in die Klassendokumentation aufgenommen).

Answer 4

Siehe auch PEP 263 wenn Sie einen Nicht-Ascii-Zeichensatz verwenden

Abstrakt

Dieses PEP schlägt die Einführung einer Syntax zur Deklaration der Kodierung von einer Python-Quelldatei zu deklarieren. Die Kodierungsinformation wird dann von der Python-Parser verwendet, um die Datei unter Verwendung der angegebenen Kodierung zu interpretieren. Die meisten Dies verbessert vor allem die Interpretation von Unicode-Literalen im Quellcode und macht es möglich, Unicode-Literale zu schreiben mit z.B. UTF-8 direkt in einem Unicode-fähigen Editor zu schreiben.

Problem

In Python 2.1 können Unicode-Literale nur mit dem Latin-1-basierte Kodierung "unicode-escape" geschrieben werden. Dies macht die Programmierumgebung ziemlich unfreundlich für Python-Benutzer, die die in Nicht-Latin-1-Gebieten leben und arbeiten, wie z.B. viele der asiatischen Länder. Programmierer können ihre 8-Bit-Zeichenfolgen mit dem Kodierung schreiben, sind aber an die "unicode-escape"-Kodierung gebunden für Unicode-Literale gebunden.

Vorgeschlagene Lösung

Ich schlage vor, die Python sauer zu machen für jede einzelne Quelldatei zu ändern, indem man einen speziellen Kommentar am Anfang der Datei, um die Kodierung zu deklarieren.

Um Python auf diese Verschlüsselung aufmerksam zu machen Konzeptänderungen in Bezug auf die Behandlung von Python-Quellcode-Daten.

Definieren der Kodierung

Python wird standardmäßig ASCII als Hinweise zur Kodierung gegeben werden.

Um eine Quellcode-Kodierung zu definieren, entweder als erster oder zweiter Kommentar in die Quelldateien eingefügt werden Zeile in die Datei eingefügt werden, wie zum Beispiel:

      # coding=<encoding name>

oder (bei Verwendung von Formaten, die von gängigen Editoren erkannt werden)

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

ou

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

...

Answer 5

Was ich in einigen Projekten verwende, ist diese Zeile in der ersten Zeile für Linux-Maschinen:

# -*- coding: utf-8 -*-

Als DOC- und Autorenkredit mag ich einfache, mehrzeilige Zeichenfolgen. Hier ein Beispiel aus Beispiel für Python-Docstrings im Google-Stil

# -*- coding: utf-8 -*-
"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

.. _Google Python Style Guide:
   http://google.github.io/styleguide/pyguide.html

"""

Es kann auch nett sein, etwas hinzuzufügen:

        """
        @Author: ...
        @Date: ....
        @Credit: ...
        @Links: ...
        """

Zusätzliche Formate

• Meta-Informationsauszeichnung | devguide

  """

        :mod:`parrot` -- Dead parrot access
        ===================================
  
        .. module:: parrot
           :platform: Unix, Windows
           :synopsis: Analyze and reanimate dead parrots.
        .. moduleauthor:: Eric Cleese <eric@python.invalid>
        .. moduleauthor:: John Idle <john@python.invalid>
    """

• /common-header-python

        #!/usr/bin/env python3  Line 1
        # -*- coding: utf-8 -*- Line 2
        #----------------------------------------------------------------------------
        # Created By  : name_of_the_creator   Line 3
        # Created Date: date/month/time ..etc
        # version ='1.0'
        # ---------------------------------------------------------------------------

Auch ich berichte ähnlich wie die anderen Antworten

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