Tutorial sulle Docstring di Python: esempi e formati per Pydoc, Numpy, Sphinx Doc Strings

Se stai iniziando con Python e vuoi saperne di più, segui il corso Introduzione alla Data Science con Python di DataCamp.

Esercitati con le Docstring in Python con questo esercizio pratico.

Cosa sono le Docstring in Python? 

La stringa di documentazione di Python, comunemente chiamata docstring, è un literal stringa utilizzato nella definizione di classi, moduli, funzioni o metodi. Le docstring sono accessibili dall'attributo doc (__doc__) per qualsiasi oggetto Python e anche con la funzione incorporata help(). La docstring di un oggetto è definita inserendo una costante stringa come prima istruzione nella definizione dell'oggetto.

A differenza dei commenti normali, che spiegano singole righe di codice, le docstring forniscono descrizioni di alto livello di cosa fa una funzione, una classe o un modulo. Docstring ben scritte migliorano la leggibilità del codice, la manutenibilità e la collaborazione, rendendole una best practice per documentare il tuo codice Python come sviluppatore Python.

Le docstring ti aiutano a capire le capacità di un modulo o di una funzione. Per esempio, se hai installato la libreria scikit-learn e vuoi sapere tutto sul pacchetto sklearn come descrizione, moduli del pacchetto, ecc., puoi semplicemente usare la funzione help per ottenere tutte le informazioni.

Importiamo rapidamente il pacchetto.

import sklearn

help(sklearn)

Vedrai un output simile a quello mostrato sotto:

Docstring in Python vs. Commenti

Le docstring sono simili nello spirito ai commenti, ma sono versioni potenziate, più logiche e utili dei commenti. Le docstring fungono da documentazione per classi, moduli e package.

I commenti, invece, sono usati principalmente per spiegare parti non ovvie del codice e possono essere utili per annotare bug da correggere e attività da svolgere.

Le docstring sono racchiuse tra virgolette di apertura e chiusura, mentre i commenti iniziano con un # all'inizio.

Nota che i commenti non sono accessibili con l'attributo incorporato doc e la funzione help. Vediamo cosa succede se provi a farlo:

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)

Ci sono un paio di modi per scrivere o usare una docstring, cioè docstring one-line e docstring multi-line. Vediamole una alla volta.

Docstring su una riga

Le docstring su una riga sono brevi descrizioni che stanno su una singola riga. Sono racchiuse tra triple virgolette (''' o """) e le virgolette di chiusura devono essere sulla stessa riga.

Sebbene funzionino sia le triple virgolette singole sia le doppie, la convenzione standard in Python è usare le triple virgolette doppie (""").

Ecco un esempio: 

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

# Accessing the docstring
print(square.__doc__)

Output:

Returns the square of the given number.

Puoi anche recuperare questa documentazione usando la funzione help() di Python:

help(square)

Output:

Help on function square in module __main__:

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

Docstring su più righe

Le docstring su più righe contengono la stessa riga di literal stringa delle docstring su una riga, ma sono seguite da una singola riga vuota insieme al testo descrittivo.

Il formato generale per scrivere una docstring su più righe è il seguente:

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

Guardiamo un esempio che mostra in dettaglio come possono essere usate le stringhe su più righe:

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.

Come vedi sopra, la riga di riepilogo è su una riga ed è separata dal resto da una singola riga vuota. È una convenzione da seguire, utile per gli strumenti di indicizzazione automatica.

Docstring integrate in Python

Vediamo le docstring integrate in Python.

Tutte le funzioni, classi, metodi incorporati hanno una descrizione in linguaggio naturale associata. Puoi accedervi in due modi.

• Attributo doc
• La funzione help

Noterai che l'output della funzione help è più dettagliato rispetto all'attributo __doc__.

Per esempio:

import math
print(math.__doc__)

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

Analogamente, puoi usare la funzione help:

help(math)

Docstring di Python nelle classi

Nella definizione di una classe, una docstring può essere usata per fornire la documentazione dell'intera classe. Di solito la si inserisce subito dopo la definizione della classe ed è racchiusa tra triple virgolette ("""). Per esempio:

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

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

Le docstring sono accessibili tramite l'attributo __doc__ della classe o del metodo. Per esempio, puoi accedere alla docstring di MyClass usando MyClass.__doc__.

Vediamo ora alcuni formati di docstring popolari e cerchiamo di capirli nel dettaglio.

Formati di docstring in Python

Esistono molti formati di docstring, ma è sempre meglio usare quelli facilmente riconosciuti dal parser di docstring e anche dagli altri data scientist/programmer. Non ci sono regole ferree per scegliere un formato, ma è necessario mantenere coerenza nello stesso progetto. Inoltre, è preferibile usare il tipo di formattazione maggiormente supportato da Sphinx.

I formati più comuni utilizzati sono elencati di seguito.

Potrebbero esserci diverse stringhe di documentazione disponibili. Non devi preoccuparti di dover reinventare la ruota per studiarle tutte. I formati delle diverse stringhe di documentazione sono quasi simili. I pattern sono simili, ma in ogni formato ci sono solo piccole differenze. Vedrai gli esempi di un formato popolare per le stringhe di documentazione insieme al loro utilizzo.

Per prima cosa vedrai lo stile Sphinx nel dettaglio, e poi potrai seguire facilmente anche gli altri formati.

Stile Sphinx

Sphinx è lo stile semplice e tradizionale, prolisso, creato inizialmente specificamente per la documentazione di Python. Sphinx usa reStructuredText, simile nell'uso a 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 usa le keyword(parole riservate) come la maggior parte dei linguaggi di programmazione. Ma in Sphinx sono chiamate esplicitamente role. Nel codice sopra, Sphinx ha param come role e type come role, che è il tipo di dato Sphinx per param. Il role type è opzionale, mentre param è obbligatorio. I role di return documentano l'oggetto restituito. È diverso dal role param. Il role return non dipende da rtype e viceversa. rtype è il tipo di oggetto restituito dalla funzione fornita.

Stile Google

Lo stile Google è più semplice e intuitivo da usare. Può essere usato per documentazione più breve. Serve una configurazione del file Python per iniziare: devi aggiungere sphinx.ext.napoleon o sphinxcontrib.napoleon alla lista extensions 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

Lo stile Google è migliore dello stile Sphinx. Ha anche una caratteristica scomoda: nel codice sopra, la descrizione su più righe di distance risulterebbe disordinata. Per questo NumPy può essere usato per una documentazione più estesa.

Stile Numpy

Lo stile Numpy include molti dettagli nella documentazione. È più prolisso di altre documentazioni, ma è un'ottima scelta se vuoi una documentazione approfondita, cioè completa di tutte le funzioni e i parametri.

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

L'esempio sopra è più prolisso di qualsiasi altra documentazione. È più lungo e andrebbe usato solo per documentazioni estese e dettagliate.

PyDoc

Come hai visto, le docstring sono accessibili tramite l'attributo incorporato di Python __doc__ e la funzione help(). Puoi anche usare il modulo incorporato chiamato Pydoc, molto diverso in termini di funzionalità rispetto all'attributo doc e alla funzione help.

Pydoc è uno strumento utile quando vuoi condividere il codice con i colleghi o renderlo open source, puntando quindi a un pubblico molto più ampio. Può generare pagine web dalla tua documentazione Python e può anche avviare un server web.

Vediamo come funziona.

Il modo più semplice e comodo per eseguire il modulo Pydoc è eseguirlo come script. Per eseguirlo all'interno di una cella di jupyter lab, userai il punto esclamativo (!).

• Pydoc come modulo

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

Se guardi l'output sopra, il primo uso di Pydoc è mostrare la documentazione testuale di una funzione, modulo, classe, ecc. Vediamo come puoi sfruttarlo meglio rispetto alla funzione help.

!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

Ora estraiamo la documentazione di glob usando la funzione help.

help(glob)

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

NameError                                 Traceback (most recent call last)

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


NameError: name 'glob' is not defined

Come vedi, genera un name error perché glob non è definito. Per usare la funzione help per estrarre la documentazione, devi prima importare quel modulo, cosa che non è richiesta con Pydoc.

• Pydoc come servizio web

Esploriamo la funzionalità più interessante del modulo Pydoc, cioè l'esecuzione di Pydoc come servizio web.

Per farlo, eseguirai semplicemente Pydoc come script ma con l'argomento -b, che avvierà un server HTTP su una porta libera a caso e aprirà un browser web per navigare interattivamente nella documentazione. Questo è utile soprattutto quando hai vari altri servizi in esecuzione sul sistema e non ricordi quale porta sia libera.

!python -m pydoc -b

^C

Nel momento in cui esegui la cella sopra, si aprirà una nuova finestra su una porta arbitraria e il browser web apparirà simile a quello mostrato sotto.

Vediamo la documentazione del modulo h5py, un formato di file usato per archiviare i pesi di un'architettura di rete neurale.

Confronto tra formati di docstring 

Nella tabella qui sotto, trovi un confronto tra i diversi tipi di formati di docstring menzionati sopra: 

• Stile Sphinx: spesso usato in progetti grandi dove serve documentazione completa. Si integra bene con il generatore di documentazione Sphinx.
• Stile Google: ideale per progetti in cui si privilegiano semplicità e leggibilità, soprattutto in organizzazioni che usano le style guide di Google.
• Stile NumPy: più adatto per progetti che richiedono documentazione dettagliata ed estesa, comune in data science e calcolo scientifico.
• PyDoc: utile per generare documentazione testuale e HTML, ma manca della struttura degli altri formati.

Conclusione

Congratulazioni per aver completato il tutorial sulle docstring in Python.

Questo tutorial si è concentrato principalmente sul farti iniziare con le docstring coprendo gli argomenti essenziali. Tuttavia, le docstring sono un tema vasto e alcuni concetti potrebbero non essere stati esplorati. Se vuoi saperne di più, dai un'occhiata al nostro tutorial sulle stringhe in Python e al corso su come scrivere funzioni in Python.

Se stai iniziando con Python e vuoi saperne di più, segui il corso Introduzione alla Data Science con Python di DataCamp. Puoi anche seguire uno dei nostri percorsi di carriera in Python e iniziare il tuo percorso per diventare Sviluppatore Python o Data Scientist con Python.