Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

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

Fuentes