CKTIS / Python
Docstrings de funciones, `__doc__` y `__name__`
Lee la documentación de una función sin llamarla y conserva su nombre y su docstring al decorarla para que las auditorías y los informes describan la función correcta.
Versión: Python 3.12
Sintaxis
def f():
"""Describe what the function does."""
...
f.__doc__
f.__name__
f.__doc__ = "Updated documentation."En Python 3.12, el docstring de una función es un literal de cadena que constituye la primera sentencia de su cuerpo. Las líneas en blanco y los comentarios no son sentencias y pueden aparecer antes. Ni un comentario #, ni un literal de cadena posterior, ni una f-string (incluso sin sustituciones) establecen __doc__. Las comillas dobles triples son una convención de PEP 257, no un requisito sintáctico.
f.__doc__ lee la documentación almacenada en el objeto función sin llamar a f. Si falta la documentación, el valor es None, no la cadena vacía ''. Este atributo se puede modificar en las funciones definidas por el usuario. Usa f.__doc__ para incluir el valor tal cual en un informe, o inspect.getdoc(f) para mostrar la documentación con la sangría normalizada. La opción -OO de CPython elimina los docstrings; no hagas que el comportamiento del programa dependa de ellos.
f.__name__ es un atributo distinto: contiene el nombre de la función, no su documentación. alias = f crea otra referencia al mismo objeto sin cambiar su nombre. Si un decorador devuelve una nueva función envoltorio sin copiar los metadatos, la auditoría lee el nombre y la documentación del envoltorio. Aplica @functools.wraps(f) a la definición del envoltorio: de forma predeterminada copia, entre otros atributos, __name__ y __doc__, y hace que __wrapped__ apunte a la función envuelta.
Ejemplos
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
El informe primero lee el docstring sin llamar a `compute_net`. Después, el envoltorio registra el nombre conservado y reenvía los argumentos; el cálculo devuelve `105`.
Lecciones relacionadas
- Python · Lección 10 · Avanzado · Versión: 5