Zugriff auf Docstrings in Python

1. Python Einzeilige Docstrings
2. Python Mehrzeilige Docstrings

Laut Python-Glossar ist docstring das erste String-Literal, das unmittelbar nach der Definition einer Klasse, Methode oder Funktion angezeigt wird.

Docstrings, die nach der Definition eines Objekts definiert werden, werden oft mit diesem bestimmten Objekt verknüpft und können mit dem Attribut __doc__ neben der Funktion print oder help() aufgerufen werden. Docstrings werden im Allgemeinen definiert, indem Stringliterale in dreifach-einfache oder dreifach-doppelte Anführungszeichen eingeschlossen werden, wie unten gezeigt:

def addtwo(x):
    """Takes in a number x and adds two to it."""
    return x + 2


print(addtwo.__doc__)

Ausgabe:

Takes in a number x and adds two to it.

Eine der bewährten Methoden zum Schreiben von sauberem Code besteht darin, einen Docstring bereitzustellen, der beschreibt, wie eine bestimmte Funktion oder ein bestimmtes Modul funktioniert. Neben der Bereitstellung wichtiger Informationen für den Entwickler können mithilfe von Sphinx-Docstrings extrahiert werden, um eine schöne Dokumentation in verschiedenen Formaten wie Klartext, HTML, ePub oder PDF zu erstellen.

Docstrings werden im Wesentlichen in zwei Kategorien eingeteilt:

• Einzeilig
• Mehrzeilig

Python Einzeilige Docstrings

Herkömmlicherweise werden Docstrings nur dann als einzeilig betrachtet, wenn sich sowohl das öffnende als auch das schließende Triple-Single oder Triple-Double in derselben Zeile befinden.

Einzelne Zeilen haben oft ein ähnliches Format und sind weniger aussagekräftig. Stattdessen bieten sie eine kurze Erläuterung der Funktion des Objekts und seines Rückgabewerts.

Außerdem sollten einzeilige docs-Strings kein führendes Leerzeichen haben und immer mit einem Großbuchstaben und einem Punkt am Ende beginnen. Das Attribut __doc__ kann auch verwendet werden, um auf einzeilige Docstrings zuzugreifen, wie unten gezeigt.

def square(x):
    """Takes in a number x and returns its square."""
    return x ** 2


print(square(10))
print(square.__doc__)

Ausgabe:

100
Takes in a number x and adds two to it.

Python Mehrzeilige Docstrings

In ähnlicher Weise werden auch mehrzeilige Docstrings durch das Einschließen von String-Literalen in dreifach-einfache oder dreifach-doppelte Anführungszeichen definiert. Mehrzeilige DokumentZeichenketten haben jedoch im Allgemeinen eine andere Struktur oder ein anderes Format.

Mehrzeilige Docstrings erstrecken sich normalerweise über mehr als eine Zeile. Die erste Zeile dient normalerweise nur der kurzen Beschreibung des Objekts.

Auf diese Beschreibung folgt eine Leerzeile und eine ausführlichere Beschreibung des Parameters, falls vorhanden, und Rückgabeargumente des Objekts in nachfolgenden Zeilen. Große Bibliotheken wie scikit learn oder pandas enthalten auch einen Abschnitt, der die in dieser Bibliothek verfügbaren Pakete auflistet.

Obwohl mehrzeilige Docstrings im Allgemeinen eine ähnliche Struktur haben, hängen einige Unterschiede vom Objekttyp ab. In Funktionsobjekten würden Docstrings der folgenden Struktur folgen.

def add_numbers(x, y):
    """
    Function takes to arguments and returns the sum of the two

         Parameter:
                 x (int): An integer
                 y (int): Another integer

        Returns:
               sum(int): Returns an integer sum of x and y

    """
    sum = x + y
    return sum


print(add_numbers.__doc__)

Ausgabe:

Function takes to arguments and returns the sum of the two
    
         Parameter:
                 x (int): An integer
                 y (int): Another integer
                 
        Returns:
               sum(int): Returns an integer sum of x and y

In großen Modulen wie Scikit, NumPy oder Pandas folgen Docstrings dem unten stehenden Format.

Wir können auch die Funktion help() und das Attribut __doc__ verwenden, um auf die Docstrings zuzugreifen, wie wir später sehen werden. Wir können das Attribut __doc__ verwenden, um auf Docstrings in Modulen wie unten zuzugreifen.

import pandas as pd

print(pd.__doc__)

Ausgabe:

Unter Klassen erstellte Docstrings sollten die Funktionalität der Klasse angeben, alle Instanzvariablen dieser bestimmten Klasse und alle öffentlichen Methoden auflisten. Klassen, die von der Hauptklasse erben, auch Unterklassen genannt, sollten ihre Docstrings haben, auf die separat zugegriffen werden kann.

Wie unten gezeigt, können Docstrings in Klassen mit dem Attribut __doc___ erstellt und darauf zugegriffen werden.

class Car:
    """
    A class to represent a car.

    ...

    Attributes
    ----------
    manufacturer : str
        company that manufactured the car
    model : str
        model of the car
    color : str
        color of the car

    Methods
    -------
    display_info():
        Prints out the car manufacturer, model and color
    """

    def __init__(self, manufacturer, model, color):
        """
        Constructs all the attributes for the car object.

        Parameters
        ----------
                manufacturer : str
                   company that manufactured the car
                model : str
                   model of the car
                color : str
                   color of the car
        """

        self.model = model
        self.color = color
        self.manufacturer = manufacturer

    def display_info(self, color, model, manufacturer):
        """
        Prints the model of the car its color and the manufacturer.

        Parameters
        ----------
        model : str
        color : str
        manufacture: str

        Returns
        -------
        None
        """

        print(f"The {self.color} {self.model} is manufactured by {self.manufacturer}")


print(Car.__doc__)
help(Car)

Ausgabe:

A class to represent a car.

    ...

    Attributes
    ----------
    manufacturer : str
        company that manufactured the car
    model : str
        model of the car
    color : str
        color of the car

    Methods
    -------
    display_info():
        Prints out the car manufacturer, model and color
    
Help on class Car in module __main__:

class Car(builtins.object)
 |  Car(manufacturer, model, color)
 |  
 |  A class to represent a car.
 |  
 |  ...
 |  
 |  Attributes
 |  ----------

Während Python-Docstrings ähnliche Rollen zu erfüllen scheinen, um Entwicklern zu helfen, ihren Code zu verstehen, werden Kommentare von Interpretern ignoriert. In Python wird einzeiligen Kommentaren ein Rautenzeichen vorangestellt und dürfen nicht mehr als eine Zeile umfassen.

Obwohl mehrzeilige Kommentare auch in dreifach-doppelten oder dreifach-einfachen Anführungszeichen geschrieben werden, folgen Kommentare im Allgemeinen keiner bestimmten Struktur. Im Gegensatz zu Docstrings, die je nach den Umständen, in denen sie verwendet wurden, leicht unterschiedliche Formate zu haben scheinen, werden Kommentare andererseits unabhängig vom Programm im Allgemeinen auf die gleiche Weise verwendet.