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 :-)
Antworten:
Es sind alle Metadaten für das
Foobar
Modul.Das erste ist das
docstring
des Moduls, das bereits in Peters Antwort erklärt wurde .Hier haben Sie weitere Informationen, die Auflistung
__author__
,__authors__
,__contact__
,__copyright__
,__license__
,__deprecated__
,__date__
und__version__
als anerkannte Metadaten.quelle
__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 -*-
Ich bevorzuge nachdrücklich minimale Datei-Header, womit ich nur meine:
#!
Zeile), wenn dies ein ausführbares Skript istdh. 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
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 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".
quelle
__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__:
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:
Warum das so ist:
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).
quelle
Siehe auch PEP 263, wenn Sie einen Nicht-ASCII-Zeichensatz verwenden
quelle