База знанияИзпитен център
BGБългарски
Избери език13

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

Източници