Docstrings in Python Tutorial

Wenn du gerade erst mit Python anfängst und mehr lernen möchtest, dann besuche den DataCamp-Kurs Einführung in die Datenwissenschaft in Python.

Übe Docstrings in Python mit dieser praktischen Übung.

Der Python-Dokumentationsstring, auch bekannt als docstring, ist ein String-Literal, das in der Klassen-, Modul-, Funktions- oder Methodendefinition verwendet wird. Docstrings sind über das doc-Attribut (__doc__) für jedes Python-Objekt und auch über die eingebaute Funktion help() zugänglich. Der Docstring eines Objekts wird definiert, indem eine String-Konstante als erste Anweisung in die Definition des Objekts aufgenommen wird.

Docstrings sind gut geeignet, um die Funktionalität des größeren Teils des Codes zu verstehen, d.h. den allgemeinen Zweck einer Klasse, eines Moduls oder einer Funktion, während die Kommentare für Code, Anweisungen und Ausdrücke verwendet werden, die eher klein sind. Sie sind beschreibender Text, den ein Programmierer hauptsächlich für sich selbst schreibt, um zu wissen, was die Codezeile oder der Ausdruck bewirkt, und auch für den Entwickler, der zu diesem Projekt beitragen möchte. Es ist wichtig, dass du deinen Python-Code dokumentierst, denn nur so kannst du sauberen Code und gut geschriebene Programme schreiben.

Docstrings helfen dir, die Fähigkeiten eines Moduls oder einer Funktion zu verstehen. Angenommen, du hast die Bibliothek scikit-learn installiert und möchtest alles über das Paket sklearn wissen, wie z. B. die Beschreibung, die Paketmodule usw., dann kannst du einfach die Funktion help verwenden, um alle Informationen zu erhalten.

Lass uns das Paket schnell importieren.

import sklearn

help(sklearn)

Du würdest eine Ausgabe ähnlich der unten gezeigten sehen:

Python Docstrings vs. Kommentiere

Docstrings sind im Prinzip ähnlich wie Kommentare, aber sie sind erweiterte, logischere und nützlichere Versionen von Kommentaren. Docstrings dienen als Dokumentation für die Klasse, das Modul und die Pakete.

Auf der anderen Seite werden Kommentare hauptsächlich dazu verwendet, nicht offensichtliche Teile des Codes zu erklären und können für Kommentare zur Behebung von Fehlern und zu erledigenden Aufgaben nützlich sein.

Docstrings werden mit schließenden und öffnenden Anführungszeichen dargestellt, während Kommentare mit einem # am Anfang beginnen.

Beachte, dass Kommentare nicht mit dem eingebauten Attribut doc und der Funktion help aufgerufen werden können. Schauen wir mal, was passiert, wenn du das versuchst:

def string_reverse(str1):
    #Returns the reversed String.

    #Parameters:
    #    str1 (str):The string which is to be reversed.

    #Returns:
    #    reverse(str1):The string which gets reversed.   

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse.__doc__)

None

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)

Es gibt zwei Möglichkeiten, einen Docstring zu schreiben oder zu verwenden, nämlich one-line docstring und multi-line docstring. Lass uns eine nach der anderen lernen.

One-Line Docstring

Die einzeiligen Docstrings sind die Docstrings, die alle in eine Zeile passen. Du kannst eines der Anführungszeichen verwenden, d.h. dreifache einfache oder dreifache doppelte Anführungszeichen, und öffnende und schließende Anführungszeichen müssen identisch sein. In den einzeiligen Docstrings stehen die schließenden Anführungszeichen in derselben Zeile wie die öffnenden Anführungszeichen. Außerdem ist es üblich, die dreifachen Anführungszeichen zu verwenden.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)

Returned argument a is squared.

help(square)

Help on function square in module __main__:

square(a)
    Returned argument a is squared.

Anhand der obigen Docstring-Ausgabe kannst du feststellen, dass:

• In diesem Fall beginnt die Zeile mit einem Großbuchstaben, z. B. R, und endet mit einem Punkt (.).
• Die schließenden Anführungszeichen stehen in derselben Zeile wie die öffnenden Anführungszeichen. Das sieht besser für Einzeiler aus.
• Eine gute Praxis ist es, keine Leerzeile vor oder nach dem Docstring zu haben, wie im obigen Beispiel gezeigt.
• Die Ausgabe des Attributs __doc__ ist weniger ausführlich als die der Funktion help().

Mehrzeiliger Docstring

Mehrzeilige Docstrings enthalten die gleiche Zeile mit Stringliteralen wie einzeilige Docstrings, aber es folgt ein einzelnes Leerzeichen zusammen mit dem beschreibenden Text.

Das allgemeine Format für das Schreiben eines mehrzeiligen Docstrings ist wie folgt:

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

help(some_function)

Help on function some_function in module __main__:

some_function(argument1)
    Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Schauen wir uns ein Beispiel an, das zeigt, wie die mehrzeiligen Strings im Detail verwendet werden können:

def string_reverse(str1):
    '''
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.   
    '''

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse('DeepLearningDataCamp'))

pmaCataDgninraeLpeeD

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.

Du kannst oben sehen, dass die Zusammenfassung in einer Zeile steht und außerdem durch eine einzelne Leerzeile vom anderen Inhalt getrennt ist. Diese Konvention muss eingehalten werden, was für die automatischen Indexierungswerkzeuge nützlich ist.

Python Built-in Docstring

Schauen wir uns die eingebauten Python Docstrings an.

Alle eingebauten Funktionen, Klassen und Methoden sind mit der tatsächlichen menschlichen Beschreibung versehen. Du kannst sie auf zwei Arten erreichen.

• doc-Attribut
• Die Hilfefunktion

Du wirst feststellen, dass die Ausgabe der Funktion help ausführlicher ist als die des Attributs __doc__.

Zum Beispiel:

import math
print(math.__doc__)

This module provides access to the mathematical functions
defined by the C standard.

Auf ähnliche Weise kannst du die Hilfefunktion nutzen:

help(math)

Python Docstring in Klassen

In einer Klassendefinition kann ein docstring verwendet werden, um die Klasse als Ganzes zu dokumentieren. Du platzierst sie normalerweise direkt nach der Klassendefinition und sie wird in dreifache Anführungszeichen (""") gesetzt. Zum Beispiel:

class MyClass:
    """This is the documentation for MyClass."""

    def __init__(self):
        """This is the documentation for the __init__ method."""
        pass

Auf Docstrings kann über das Attribut __doc__ der Klasse oder Methode zugegriffen werden. Du könntest zum Beispiel mit MyClass.__doc__ auf den Docstring für MyClass zugreifen.

Schauen wir uns nun einige beliebte Docstring-Formate an und verstehen sie im Detail.

Python Docstring Formate

Es gibt viele Docstring-Formate, aber es ist immer besser, die Formate zu verwenden, die vom Docstring-Parser und auch von anderen Data Scientists/Programmierern leicht erkannt werden. Es gibt keine Regeln und Vorschriften für die Auswahl eines Docstring-Formats, aber es ist wichtig, dass du im Laufe des Projekts immer wieder dasselbe Format wählst. Außerdem solltest du den Formatierungstyp verwenden, der von Sphinx am meisten unterstützt wird.

Im Folgenden sind die gängigsten Formate aufgeführt.

Es können verschiedene Dokumentationsstrings verfügbar sein. Du brauchst dir keine Sorgen zu machen, dass du das Rad neu erfinden musst, um alles zu lernen. Die Formate aller Dokumentationsstrings sind fast gleich. Die Muster sind ähnlich, aber es gibt nur kleine Änderungen in jedem Format. Du wirst dir das Beispiel eines beliebten Formats für Dokumentationsstrings ansehen, das für ihre Verwendung zur Verfügung steht.

Zuerst siehst du den Sphinx-Stil im Detail, und dann kannst du auch mit anderen Formaten leicht mitkommen.

Sphinx-Stil

Sphinx ist der einfache und traditionelle Stil, wortreich, und wurde ursprünglich speziell für die Python-Dokumentation entwickelt. Sphinx verwendet einen reStructured Text, der ähnlich wie Markdown verwendet wird.

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The keyword arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''


    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''  
        pass

Sphinx verwendet die keyword(reserved word); die meisten Programmiersprachen tun dies. Aber in Sphinx wird es ausdrücklich role genannt. Im obigen Code hat Sphinx die param als Rolle, und type ist eine Rolle, die der Sphinx-Datentyp für param ist. type Rolle ist optional, aber param ist Pflicht. Die Rückgaberollen dokumentieren das zurückgegebene Objekt. Sie unterscheidet sich von der Param-Rolle. Die Rückgabefunktion ist nicht vom rtype abhängig und umgekehrt. Der rtype ist der Typ des Objekts, das von der angegebenen Funktion zurückgegeben wird.

Google Style

Google Style ist einfacher und intuitiver zu bedienen. Sie kann für die kürzere Form der Dokumentation verwendet werden. Um loszulegen, muss eine Python-Konfigurationsdatei erstellt werden. Du musst also entweder sphinx.ext.napoleon oder sphinxcontrib.napoleon zur Liste der Erweiterungen in conf.py hinzufügen.

class Vehicles(object):
    '''
    The Vehicle object contains a lot of vehicles

    Args:
        arg (str): The arg is used for...
        *args: The variable arguments are used for...
        **kwargs: The keyword arguments are used for...

    Attributes:
        arg (str): This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance,destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Args:
            distance (int): The amount of distance traveled
            destination (bool): Should the fuels refilled to cover the distance?

        Raises:
            RuntimeError: Out of fuel

        Returns:
            cars: A car mileage
        '''
        pass

Der Google-Stil ist besser als der Sphinx-Stil. Es hat auch eine unpraktische Eigenschaft, d.h. im obigen Code würde die mehrzeilige Beschreibung der Entfernung unordentlich aussehen. Deshalb kann das Numpy für die erweiterte Form der Dokumentation verwendet werden.

Numpy-Stil

Der Numpy-Stil hat eine Menge Details in der Dokumentation. Sie ist ausführlicher als andere Dokumentationen, aber sie ist eine ausgezeichnete Wahl, wenn du eine detaillierte Dokumentation, d.h. eine ausführliche Dokumentation aller Funktionen und Parameter, erstellen willst.

class Vehicles(object):
    '''
    The Vehicles object contains lots of vehicles

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        '''
        pass

Das obige Beispiel ist ausführlicher als jede andere Dokumentation. Es ist langwieriger und könnte nur für die lange und detaillierte Dokumentation verwendet werden.

PyDoc

Wie du gelernt hast, sind docstrings über das eingebaute Python-Attribut __doc__ und die Funktion help() zugänglich. Du könntest auch das eingebaute Modul Pydoc verwenden, das sich in Bezug auf die Eigenschaften und Funktionen von dem doc-Attribut und der Hilfefunktion unterscheidet.

Pydoc ist ein nützliches Tool, wenn du den Code mit deinen Kollegen teilen oder ihn als Open Source zur Verfügung stellen möchtest, um ein breiteres Publikum anzusprechen. Es kann Webseiten aus deiner Python-Dokumentation generieren und auch einen Webserver starten.

Schauen wir mal, wie es funktioniert.

Der einfachste und bequemste Weg, das Pydoc-Modul auszuführen, ist, es als Skript zu starten. Um sie innerhalb der Jupyter-Labarzelle auszuführen, musst du das Ausrufezeichen (!) verwenden.

• Pydoc als Modul

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Wenn du dir die obige Ausgabe ansiehst, ist die allererste Verwendung von Pydoc die Anzeige der Textdokumentation einer Funktion, eines Moduls, einer Klasse usw., also schauen wir mal, wie du das besser nutzen kannst als die Hilfefunktion.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Jetzt wollen wir die Dokumentation von glob mit Hilfe der Hilfefunktion extrahieren.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-6-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Wie du sehen kannst, wird ein Namensfehler ausgegeben, da glob nicht definiert ist. Damit du die Hilfefunktion zum Extrahieren der Dokumentation nutzen kannst, musst du das Modul zunächst importieren, was in Pydoc nicht der Fall ist.

• Pydoc als Webdienst

Sehen wir uns die interessanteste Funktion des Pydoc-Moduls an, nämlich die Ausführung von Pydoc als Webservice.

Dazu führst du Pydoc einfach als Skript aus, aber mit einem -b Argument, das einen HTTP-Server auf einem beliebigen unbenutzten Port startet und einen Webbrowser öffnet, um die Dokumentation interaktiv zu durchsuchen. Das ist vor allem dann hilfreich, wenn du verschiedene andere Dienste auf deinem System laufen hast und nicht mehr weißt, welcher Port sich im Leerlauf befindet.

!python -m pydoc -b

^C

In dem Moment, in dem du die obige Zelle ausführst, öffnet sich ein neues Fenster auf einer beliebigen Portnummer und der Webbrowser sieht ähnlich aus wie der unten abgebildete.

Schauen wir uns die Dokumentation des Moduls h5py an, das ein Dateiformat zum Speichern von Gewichten der neuronalen Netzarchitektur ist.

Fazit

Herzlichen Glückwunsch zum Abschluss des Docstring in Python-Tutorials.

Dieses Tutorial konzentriert sich in erster Linie darauf, dir den Einstieg in die Arbeit mit Docstrings zu erleichtern, indem es die wichtigsten Themen behandelt. Das Thema Docstrings ist jedoch sehr umfangreich, und einige Konzepte sind vielleicht noch unerforscht. Wenn du mehr erfahren möchtest, dann schau dir unser Python-String-Tutorial und unseren Kurs zum Schreiben von Funktionen in Python an.

Wenn du gerade erst mit Python anfängst und mehr lernen möchtest, dann besuche den DataCamp-Kurs Einführung in die Datenwissenschaft in Python.