Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Python

Docstrings de funções, `__doc__` e `__name__`

Lê a documentação de uma função sem a chamar e preserva o nome e a docstring ao decorá-la, para que os registos de auditoria e os relatórios descrevam a função certa.

Versão: Python 3.12

Sintaxe

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

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

Em Python 3.12, a docstring de uma função é um literal de cadeia de caracteres que constitui a primeira instrução do corpo. As linhas em branco e os comentários não são instruções e podem aparecer antes. Nem um comentário #, nem um literal de cadeia posterior, nem uma f-string (mesmo sem substituições) definem __doc__. As aspas duplas triplas são uma convenção da PEP 257, não um requisito sintático.

f.__doc__ lê a documentação guardada no objeto função sem chamar f. Se a documentação estiver ausente, o valor é None, não a cadeia vazia ''. Nas funções definidas pelo utilizador, este atributo pode ser alterado. Usa f.__doc__ para incluir o valor tal como está num relatório, ou inspect.getdoc(f) para apresentar a documentação com a indentação normalizada. A opção -OO do CPython elimina as docstrings; não faças depender delas o comportamento do programa.

f.__name__ é um atributo distinto: contém o nome da função, não a sua documentação. alias = f cria outra referência ao mesmo objeto sem lhe mudar o nome. Se um decorador devolver uma nova função envolvente sem copiar os metadados, a auditoria lê o nome e a documentação dessa função envolvente. Aplica @functools.wraps(f) à sua definição: por omissão, copia, entre outros atributos, __name__ e __doc__ e faz com que __wrapped__ referencie a função envolvida.

Exemplos

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

Resultado

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

O relatório começa por ler a docstring sem chamar `compute_net`. Em seguida, a função envolvente regista o nome preservado e encaminha os argumentos; o cálculo devolve `105`.

Lições relacionadas

  • Python · Lição 10 · Avançado · Versão: 5

Fontes