Python-docstrings-tutorial: voorbeelden en opmaak voor Pydoc, Numpy, Sphinx-docstrings

Als je net begint met Python en meer wilt leren, volg dan DataCamp's cursus Introduction to Data Science in Python.

Oefen docstrings in Python met deze praktische opdracht.

Wat zijn Python-docstrings? 

Een Python-documentatiestring, beter bekend als docstring, is een stringliteral die wordt gebruikt in de definitie van een class, module, functie of methode. Docstrings zijn toegankelijk via het doc-attribuut (__doc__) voor elk Python-object en ook via de ingebouwde functie help(). De docstring van een object wordt gedefinieerd door een stringconstante op te nemen als de eerste instructie in de definitie van het object.

In tegenstelling tot gewone comments, die individuele codelijnen toelichten, geven docstrings een beschrijving op hoog niveau van wat een functie, class of module doet. Goed geschreven docstrings verbeteren de leesbaarheid, onderhoudbaarheid en samenwerking, waardoor ze een best practice zijn voor het documenteren van je Python-code als Python-ontwikkelaar.

Docstrings helpen je de mogelijkheden van een module of functie te begrijpen. Stel bijvoorbeeld dat je de bibliotheek scikit-learn hebt geïnstalleerd en je alles wilt weten over het sklearn-pakket, zoals de beschrijving, packagemodules, enz. Dan kun je eenvoudig de functie help gebruiken om alle informatie op te vragen.

Importeer het pakket snel even.

import sklearn

help(sklearn)

Je ziet dan een uitvoer die lijkt op die hieronder:

Python-docstrings vs. commentaar

Docstrings lijken qua doel op commentaar, maar zijn uitgebreidere, logischere en nuttigere varianten. Docstrings fungeren als documentatie voor classes, modules en packages.

Commentaar daarentegen wordt vooral gebruikt om niet-voor-de-hand-liggende delen van de code toe te lichten en kan nuttig zijn voor opmerkingen over het oplossen van bugs en taken die nog moeten worden gedaan.

Docstrings worden weergegeven met openings- & sluitingstekens, terwijl commentaar begint met een # aan het begin.

Let op dat commentaar niet toegankelijk is via het ingebouwde doc-attribuut en de help-functie. Laten we zien wat er gebeurt als je dit toch probeert:

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)

Er zijn een paar manieren om een docstring te schrijven of te gebruiken, namelijk een one-line docstring en een multi-line docstring. Laten we ze één voor één doornemen.

One-line docstring

One-line docstrings zijn korte beschrijvingen die op één regel passen. Ze staan tussen drie aanhalingstekens (''' of """), en de sluitende aanhalingstekens moeten op dezelfde regel staan.

Hoewel zowel drie enkele als drie dubbele aanhalingstekens werken, is de standaardconventie in Python om drie dubbele aanhalingstekens (""") te gebruiken.

Hier is een voorbeeld: 

def square(a):
    """Returns the square of the given number."""
    return a ** 2  # Corrected exponentiation

# Accessing the docstring
print(square.__doc__)

Uitvoer:

Returns the square of the given number.

Je kunt deze documentatie ook opvragen met de Python-functie help():

help(square)

Uitvoer:

Help on function square in module __main__:

square(a)
    Returns the square of the given number.

Multi-line docstring

Multi-line docstrings bevatten dezelfde stringliteral als bij one-line docstrings, maar gevolgd door een enkele lege regel en daarna de beschrijvende tekst.

De algemene opmaak voor een multi-line docstring is als volgt:

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

Laten we naar een voorbeeld kijken dat laat zien hoe je multi-line strings in detail kunt gebruiken:

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.

Je ziet hierboven dat de samenvattingsregel op één regel staat en door een enkele lege regel van de rest is gescheiden. Deze conventie moet worden gevolgd en is nuttig voor automatische indexeringstools.

Ingebouwde Python-docstring

Bekijk de ingebouwde Python-docstrings.

Alle ingebouwde functies, classes en methoden hebben een echte, menselijke beschrijving eraan gekoppeld. Je kunt die op twee manieren benaderen.

• doc-attribuut
• De help-functie

Je zult merken dat de uitvoer van de functie help uitgebreider is dan het attribuut __doc__.

Bijvoorbeeld:

import math
print(math.__doc__)

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

Op dezelfde manier kun je de help-functie gebruiken:

help(math)

Python-docstring in classes

In een class-definitie kun je een docstring gebruiken om documentatie te geven voor de class als geheel. Je plaatst deze meestal direct na de class-definitie en zet hem tussen drie aanhalingstekens ("""). Bijvoorbeeld:

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

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

Docstrings zijn toegankelijk via het attribuut __doc__ van de class of methode. Je kunt bijvoorbeeld de docstring voor MyClass benaderen met MyClass.__doc__.

Laten we nu een paar populaire docstringformaten bekijken en ze in detail begrijpen.

Python-docstringformaten

Er zijn veel docstringformaten beschikbaar, maar het is altijd beter om formaten te gebruiken die eenvoudig worden herkend door de docstringparser en ook door mede-data scientists/programmeurs. Er zijn geen regels voor het kiezen van een docstringformaat, maar consistentie binnen hetzelfde project is noodzakelijk. Ook heeft het de voorkeur om het type opmaak te gebruiken dat grotendeels door Sphinx wordt ondersteund.

De meest voorkomende formaten staan hieronder vermeld.

Er kunnen verschillende documentatiestrings beschikbaar zijn. Je hoeft je geen zorgen te maken dat je het wiel opnieuw moet uitvinden om ze allemaal te bestuderen. De formaten van alle documentatiestrings zijn bijna gelijk. De patronen zijn vergelijkbaar, maar er zijn slechts kleine verschillen in elk formaat. Je bekijkt voorbeelden van een populair formaat voor documentatiestrings met hun gebruik.

Eerst zie je de Sphinx-stijl in detail, daarna kun je de andere formaten eenvoudig volgen.

Sphinx-stijl

Sphinx is de eenvoudige en traditionele stijl, uitgebreid, en is oorspronkelijk specifiek gemaakt voor Python-documentatie. Sphinx gebruikt reStructuredText, wat in gebruik vergelijkbaar is met Markdown.

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 gebruikt het keyword(reserved word) zoals de meeste programmeertalen dat doen. In Sphinx heet dit expliciet een role. In de bovenstaande code is param een rol en type is een rol, wat het Sphinx-datatype voor param is. De rol type is optioneel, maar param is verplicht. De return-rollen documenteren het geretourneerde object. Dat verschilt van de param-rol. De return-rol is niet afhankelijk van de rtype en omgekeerd. De rtype is het type object dat door de functie wordt geretourneerd.

Google-stijl

Google-stijl is makkelijker en intuïtiever in gebruik. Het kan worden gebruikt voor kortere documentatie. Er is een configuratie van een Python-bestand nodig om te beginnen: je moet ofwel sphinx.ext.napoleon of sphinxcontrib.napoleon toevoegen aan de extensions-lijst in conf.py.

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

De Google-stijl is beter dan de Sphinx-stijl. Hij heeft ook een onhandige eigenschap: in de bovenstaande code zou de beschrijving over meerdere regels voor distance rommelig ogen. Daarom kan Numpy worden gebruikt voor een meer uitgebreide vorm van documentatie.

Numpy-stijl

Numpy-stijl bevat veel details in de documentatie. Het is uitgebreider dan andere documentaties, maar een uitstekende keuze als je gedetailleerde documentatie wilt, d.w.z. uitgebreide documentatie van alle functies en parameters.

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

Het bovenstaande voorbeeld is uitgebreider dan andere documentatie. Het is langer en kan het best worden gebruikt voor lange en gedetailleerde documentatie.

PyDoc

Zoals je hebt geleerd, zijn docstrings toegankelijk via het ingebouwde Python-attribuut __doc__ en de functie help(). Je kunt ook gebruikmaken van de ingebouwde module Pydoc, die qua features en functionaliteit sterk verschilt van het attribuut doc en de help-functie.

Pydoc is een tool die van pas komt wanneer je code wilt delen met collega's of open source wilt maken, in welk geval je een veel breder publiek bedient. Het kan webpagina's genereren op basis van je Python-documentatie en ook een webserver starten.

Laten we zien hoe dit werkt.

De makkelijkste en handigste manier om de Pydoc-module uit te voeren is deze als script draaien. Om hem binnen een Jupyter Lab-cel uit te voeren, gebruik je het uitroepteken (!).

• Pydoc als module

!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.

Als je naar de bovenstaande uitvoer kijkt, is het eerste gebruik van Pydoc het tonen van tekstdocumentatie van een functie, module, class, enz. Laten we zien hoe je dat beter kunt benutten dan met de help-functie.

!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

Laten we nu de documentatie voor glob opvragen met de help-functie.

help(glob)

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

NameError                                 Traceback (most recent call last)

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


NameError: name 'glob' is not defined

Zoals je ziet, geeft dit een NameError omdat glob niet is gedefinieerd. Om de help-functie te gebruiken voor het ophalen van de documentatie, moet je die module eerst importeren, wat bij Pydoc niet nodig is.

• Pydoc als webservice

Laten we de interessantste functie van de Pydoc-module verkennen, namelijk Pydoc draaien als webservice.

Hiervoor voer je Pydoc simpelweg uit als script maar met het argument -b, waarmee een HTTP-server wordt gestart op een willekeurige ongebruikte poort en een webbrowser wordt geopend om de documentatie interactief te bekijken. Dit is handig, vooral als er al verschillende services op je systeem draaien en je niet meer weet welke poort vrij is.

!python -m pydoc -b

^C

Op het moment dat je de bovenstaande cel uitvoert, opent er een nieuw venster op een willekeurig poortnummer en ziet de webbrowser eruit zoals hieronder weergegeven.

Bekijk de documentatie van de module h5py, een bestandsformaat dat wordt gebruikt om gewichten van neurale netwerken op te slaan.

Vergelijking van docstringformaten 

In de onderstaande tabel zie je een vergelijking van de verschillende typen docstringformaten die we hierboven hebben genoemd: 

• Sphinx-stijl: Wordt vaak gebruikt in grote projecten waar uitgebreide documentatie vereist is. Integreert goed met de documentatiegenerator van Sphinx.
• Google-stijl: Ideaal voor projecten waar eenvoud en leesbaarheid prioriteit hebben, vooral binnen organisaties die de stijlgidsen van Google gebruiken.
• NumPy-stijl: Het meest geschikt voor projecten die gedetailleerde en uitgebreide documentatie vereisen, gebruikelijk in data science en wetenschappelijk rekenen.
• PyDoc: Handig voor het genereren van tekst- en HTML-documentatie, maar mist het gestructureerde formaat van de anderen.

Conclusie

Gefeliciteerd met het afronden van de tutorial over docstrings in Python.

Deze tutorial was vooral gericht op een vliegende start met docstrings door de essentiële onderwerpen te behandelen. Docstrings is echter een uitgebreid onderwerp en sommige concepten zijn mogelijk onbesproken gebleven. Wil je meer leren, bekijk dan onze Python-stringtutorial en onze cursus over functies schrijven in Python.

Als je net begint met Python en meer wilt leren, volg dan DataCamp's cursus Introduction to Data Science in Python. Je kunt ook een van onze Python-carrièretracks volgen en beginnen aan je traject naar Python Developer of Data Scientist met Python.