Python Style Guide

Allgemeine Regeln

Für Python-Dateien gelten die Formatierungsrichtlinien, die in PEP 8 [PEP8] formuliert sind. Nachfolgend eine kurze Zusammenfassung der wichtigsten Punkte:

• Eine Einrückungsebene in Python entspricht genau 4 Leerzeichen (keine Tabulatorzeichen). Falls Sie Tabulatorzeichen verwenden, achten Sie darauf, dass Ihr Editor diese beim Speichern der Datei zu jeweils 4 Leerzeichen expandiert.
• Jede Zeile soll aus höchstens 79 Zeichen bestehen. Es gibt sehr seltene Ausnahmen von dieser Regel.
• Funktionen, die nicht innerhalb anderer Funktionen definiert werden, (sogenannte Funktionen auf Modulebene) sollen durch zwei Leerzeilen getrennt werden.
• Funktionsnamen bestehen ausschließlich aus Kleinbuchstaben: Unterstriche sind erlaubt, wenn dies die Lesbarkeit des Codes verbessert. Entsprechendes gilt für Variablennamen (siehe [PEP8]).
• Am Anfang jeder Python-Datei steht ein Doc-String der kurz den Inhalt der Datei bescheibt. Dies ist auch der geeignete Ort, um Metadaten (z.B. Informationen zum Autor, Lizenz, etc.) zu listen.
• Jede definierte Funktion wird mit einem Doc-String versehen werden. Im Rahmen der Vorlesung verwenden wir dazu ein Schema in Anlehnung an PEP 257 [PEP257] und dem Google Python Style Guide [GPSG]. Siehe hierzu Doc-Strings.
• Am Ende der Datei sind alle Leerzeilen zu entfernen.

Eine kleine Beispieldatei können Sie hier herunterladen und als Template für Ihre eigenen Python-Dateien benutzen.

Doc-Strings

Die Dokumentierung von Code ist wichtig, nicht nur (aber besonders) wenn Sie den Code veröffentlichen. Zur Dokumentation verwendet man in Python Doc-Strings. Diese Doc-Strings können ferner verwendet werden, um automatisch eine Dokumentation von Python-Modulen zu erzeugen (siehe z.B. [Sphinx]). Sie können aber auch verwendet werden, um mittels Doc-Tests zu prüfen, ob die dokumentierte Funktionsweise von Funktionen mit deren Implementierung übereinstimmt.

Wie diese Doc-Strings aufgebaut sind hängt, vom jeweiligen Kontext ab. Ein Doc-String am Beginn des Python-Moduls sollte eine kurz die im Modul implementierte Funktionalität beschreiben. Dies ist auch der geeignete Ort, um Meta-Daten abzulegen: wer hat an dem Modul mitgeschrieben, mit welcher Lizenz wird die Datei weitergegeben, die Versionsnummer des Moduls, ein knapper ChangeLog der Versionen, etc.

Der Doc-String des Moduls könnte in etwa wie folgt aussehen:

"""String tools.

This module defines some helper function often used but not found in the
`Python Standard Library`_.

Authors:
    Your Name <your-name@address.de>


.. _`Python Standard Library`:
    https://docs.python.org/3.5/library

"""

Für die Dokumentation von Funktionen beachten Sie bitte ebenfalls den Google Python Style Guide [GPSG]. Betrachten wir dazu das folgende Beispiel (ein bei weitem ausführlicheres Beispiel finden Sie auf der Webseite des Sphinx-Pakets Napoleon [Nap]):

def charcount(char, string):
    """Calculate the number of occurences of a character in a string.

    If reasonable, a more elaborate description of the function follows (not
    needed here).

    Args:
        char (str): A string of length 1.
            Some further description of the parameter char is indented.
        string (str): A string.

    Returns:
        int or None: int if ``char`` is a string of length 1; None otherwise.

    Notes:
        Python has no own type for characters. If we had introduced exceptions
        in the lecture, we would throw some on non-legal inputs. Instead we are
        returning ``None`` in this case.

    Examples:

        >>> charcount("s", "spamam")
        1
        >>> charcount("a", "spamam")
        2
        >>> charcount("x", "spamam")
        0
        >>> x = charcount("am", "spamam")
        >>> x is None
        True

    """
    pass  # Implementation follows here

Die erste Zeile ist wieder eine kurze Zusammenfassung dessen, was die Funktion macht (typischerweise in Befehlsform geschrieben), ggfs. gefolgt von einer genaueren Beschreibung. Anschließend werden die Argumente der Funktion sowie deren Rückgabewert beschrieben. Danach dokumentiert ein “Examples”-Abschnitt die Verwendungsweise der Funktion. Beachten Sie insbesondere die Leerzeilen und die Einrückungen in diesem Beispiel.

Bemerkung

Bei der Abgabe von Übungsblättern sollte der Doc-String einer Funktion stets Folgendes enthalten: die Kurzbeschreibung der Funktion, die Dokumentation der Parameter und die des Rückgabewerts.

Ebenso müssen Klassen mit Doc-Strings versehen werden. Beispiel:

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

References

[PEP8]

(1, 2) Guido van Rossum et al.: Style Guide for Python Code (PEP 8). URL: http://legacy.python.org/dev/peps/pep-0008/

[PEP257]

David Goodger und Guido van Rossum: Docstring Conventions (PEP 257). Online verfügbar unter: http://legacy.python.org/dev/peps/pep-0257/

[GPSG]

(1, 2) Amit Patel et al.: Google Python Style Guide. URL: https://google.github.io/styleguide/pyguide.html

[Sphinx]

Georg Brandl and the Sphinx team: Sphinx Python Documentation Generator URL: http://sphinx-doc.org

[Nap]

Rob Ruana: Napoleon Sphinx Package: Example Google Style Python Docstrings URL: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html#example-google

[RST]

Georg Brandl and the Sphinx team: reStructuredText Primer. URL: http://sphinx-doc.org/rest.html