CKTIS / Python
Документационни низове на функции, `__doc__` и `__name__`
Прочети документацията на функция без извикване и запази името и документационния ѝ низ при декориране, така че одитните записи и отчетите да описват правилната функция.
Версия: Python 3.12
Синтаксис
def f():
"""Describe what the function does."""
...
f.__doc__
f.__name__
f.__doc__ = "Updated documentation."В Python 3.12 документационният низ на функция (docstring) е низов литерал, който е първата инструкция в тялото ѝ. Празните редове и коментарите не са инструкции и могат да го предхождат. Нито коментар с #, нито низов литерал по-нататък, нито f-низ (дори без замествания) задава __doc__. Тройните двойни кавички са конвенция от PEP 257, а не синтактично изискване.
f.__doc__ прочита документацията, съхранена в обекта на функцията, без да извиква f. Ако документацията липсва, стойността е None, а не празният низ ''. При потребителски дефинираните функции този атрибут може да се променя. Използвай f.__doc__ за непроменената стойност в отчет или inspect.getdoc(f) за показване на документацията с подравнени отстъпи. Опцията -OO на CPython премахва документационните низове, затова не прави поведението на програмата зависимо от тях.
f.__name__ е отделен атрибут: съдържа името на функцията, а не документацията ѝ. Присвояването alias = f създава още една препратка към същия обект, без да променя името му. Ако декоратор върне нова обвиваща функция, без да копира метаданните, одитът вижда името и документацията на обвивката. Приложи @functools.wraps(f) към дефиницията на обвивката: по подразбиране той копира, наред с други атрибути, __name__ и __doc__ и задава __wrapped__ да сочи към обвитата функция.
Примери
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)}")Резултат
Documentation: 'Return gross minus fee.' Audit: compute_net Net: 105
Отчетът първо прочита документационния низ, без да извиква `compute_net`. След това обвивката записва запазеното име в одитния журнал и предава аргументите; изчислението връща `105`.
Свързани уроци
- Python · Урок 10 · Напреднало · Версия: 5