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