Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / Python

Docstringi i atrybuty `__doc__` oraz `__name__` funkcji

Odczytuj dokumentację funkcji bez jej wywoływania i zachowuj jej nazwę oraz docstring po dekorowaniu, aby audyt i raport opisywały właściwą funkcję.

Wersja: Python 3.12

Składnia

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

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

W Pythonie 3.12 docstring funkcji to literał tekstowy stanowiący pierwszą instrukcję jej ciała. Puste wiersze i komentarze nie są instrukcjami, więc mogą go poprzedzać. Sam komentarz #, literał tekstowy umieszczony później ani f-string (nawet bez podstawień) nie ustawiają __doc__. Potrójne cudzysłowy są konwencją PEP 257, a nie wymogiem składni.

f.__doc__ odczytuje dokumentację zapisaną w obiekcie funkcji bez wywoływania f. Brak dokumentacji oznacza None, a nie pusty napis ''. W funkcji zdefiniowanej przez użytkownika atrybut ten można zmienić. Do raportu pokazującego wartość bez zmian użyj f.__doc__; do wyświetlenia dokumentacji z uporządkowanymi wcięciami użyj inspect.getdoc(f). CPython z opcją -OO usuwa docstringi, więc nie uzależniaj od nich działania programu.

f.__name__ to osobny atrybut: zawiera nazwę funkcji, nie jej dokumentację. Przypisanie alias = f tworzy drugie odwołanie do tego samego obiektu i nie zmienia jego nazwy. Jeśli dekorator zwraca nową funkcję opakowującą, bez kopiowania metadanych audyt widzi nazwę i dokumentację tej funkcji opakowującej. Użyj @functools.wraps(f) przy jej definicji: domyślnie kopiuje między innymi __name__ i __doc__ oraz ustawia __wrapped__ na opakowaną funkcję.

Przykłady

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

Wynik

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

Najpierw raport odczytuje docstring bez wywołania `compute_net`. Następnie funkcja opakowująca wypisuje w audycie zachowaną nazwę i przekazuje argumenty; obliczenie daje `105`.

Powiązane lekcje

  • Python · Lekcja 10 · Zaawansowany · Wersja: 5

Źródła