KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / Python

Docstrings van functies, `__doc__` en `__name__`

Lees de documentatie van een functie zonder haar aan te roepen en behoud de naam en docstring bij het decoreren, zodat auditlogs en rapporten de juiste functie beschrijven.

Versie: Python 3.12

Syntax

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

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

In Python 3.12 is de docstring van een functie een stringliteral die de eerste instructie in de functiebody vormt. Lege regels en commentaar zijn geen instructies en mogen er dus vóór staan. Een #-commentaarregel, een latere stringliteral of een f-string (zelfs zonder vervangingsvelden) stelt __doc__ niet in. Drie dubbele aanhalingstekens zijn een conventie uit PEP 257, geen syntactische eis.

f.__doc__ leest de documentatie op het functieobject zonder f aan te roepen. Als documentatie ontbreekt, is de waarde None, niet de lege string ''. Bij zelfgedefinieerde functies kun je dit attribuut wijzigen. Gebruik f.__doc__ om de opgeslagen waarde ongewijzigd te rapporteren, of inspect.getdoc(f) om documentatie met opgeschoonde inspringing te tonen. De CPython-optie -OO verwijdert docstrings; laat het gedrag van je programma er dus niet van afhangen.

f.__name__ is een apart attribuut: het bevat de naam van de functie, niet haar documentatie. Met alias = f maak je een tweede verwijzing naar hetzelfde object zonder de naam ervan te wijzigen. Als een decorator een nieuwe wrapperfunctie teruggeeft zonder metadata te kopiëren, ziet een audit de naam en documentatie van de wrapper. Gebruik @functools.wraps(f) bij de definitie van de wrapper: standaard kopieert dit onder meer __name__ en __doc__ en laat het __wrapped__ naar de ingepakte functie verwijzen.

Voorbeelden

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)}")

Resultaat

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

Het rapport leest eerst de docstring zonder `compute_net` aan te roepen. Daarna logt de wrapper de behouden naam en geeft hij de argumenten door; de berekening geeft `105` terug.

Gerelateerde lessen

  • Python · Les 10 · Gevorderd · Versie: 5

Bronnen