Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / Python

Docstring delle funzioni, `__doc__` e `__name__`

Leggi la documentazione di una funzione senza chiamarla e conserva il nome e la docstring quando la decori, affinché i log di audit e i report descrivano la funzione corretta.

Versione: Python 3.12

Sintassi

def f():
    """Describe what the function does."""
    ...

f.__doc__
f.__name__
f.__doc__ = "Updated documentation."

In Python 3.12, la docstring di una funzione è un letterale stringa che costituisce la prima istruzione del corpo. Le righe vuote e i commenti non sono istruzioni, quindi possono precederlo. Né un commento #, né un letterale stringa successivo, né una f-string (anche senza sostituzioni) impostano __doc__. Le virgolette doppie triple sono una convenzione della PEP 257, non un requisito sintattico.

f.__doc__ legge la documentazione memorizzata nell’oggetto funzione senza chiamare f. Se manca la documentazione, il valore è None, non la stringa vuota ''. Nelle funzioni definite dall’utente questo attributo è modificabile. Usa f.__doc__ per riportare il valore così com’è oppure inspect.getdoc(f) per visualizzare la documentazione con l’indentazione normalizzata. L’opzione -OO di CPython elimina le docstring: non far dipendere da esse il comportamento del programma.

f.__name__ è un attributo distinto: contiene il nome della funzione, non la sua documentazione. alias = f crea un altro riferimento allo stesso oggetto senza rinominarlo. Se un decoratore restituisce una nuova funzione wrapper senza copiare i metadati, l’audit legge il nome e la documentazione del wrapper. Applica @functools.wraps(f) alla definizione del wrapper: per impostazione predefinita copia, tra gli altri attributi, __name__ e __doc__ e fa puntare __wrapped__ alla funzione avvolta.

Esempi

from functools import wraps


def audit(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Audit: {wrapper.__name__}")
        return func(*args, **kwargs)

    return wrapper


@audit
def compute_net(gross, fee):
    """Return gross minus fee."""
    return gross - fee


print(f"Documentation: {compute_net.__doc__!r}")
print(f"Net: {compute_net(120, fee=15)}")

Risultato

Documentation: 'Return gross minus fee.'
Audit: compute_net
Net: 105

Il report legge prima la docstring senza chiamare `compute_net`. Il wrapper registra poi il nome conservato e inoltra gli argomenti; il calcolo restituisce `105`.

Lezioni correlate

  • Python · Lezione 10 · Avanzato · Versione: 5

Fonti