Saltearse al contenido

Decoradores

@decorador es azúcar sintáctico para f = decorador(f). Nada más. Pero esa línea explica por qué los frameworks de Python funcionan: no es que @app.route registre una ruta por magia, es que recibe la función y devuelve otra que hace algo antes o después. Entender el mecanismo es la diferencia entre usar Flask y saber por qué Flask funciona.

Un decorador recibe una función, devuelve otra, y ambas son objetos.

def registrar(f):
def envoltorio(*args, **kwargs):
print(f"llamando a {f.__name__}")
return f(*args, **kwargs)
return envoltorio
def sumar(a, b):
return a + b
sumar = registrar(sumar) # equivalente a @registrar
sumar(2, 3) # imprime y devuelve 5

Las tres piezas: la función que decora recibe f, define envoltorio que la llama, y devuelve envoltorio. El *args, **kwargs es lo que permite decorar cualquier firma sin conocerla.

Un millón de llamadas
Llamada Coste Frente a la directa
Función sin decorar 41 ns 1.0×
Función decorada 139 ns 3.4×

python mediciones/03-01-04-funciones.py

Tres veces y media, porque cada llamada atraviesa una función Python más y empaqueta los argumentos en una tupla y un diccionario. En una ruta web da igual; en un bucle de diez millones de iteraciones, no.

Sin wraps, el decorador sustituye la función por envoltorio y con ella su identidad:

sumar.__name__ # 'envoltorio' — el nombre se perdió
sumar.__doc__ # el del envoltorio, no el de sumar

functools.wraps copia __name__, __doc__, __module__, __qualname__, __dict__ y __wrapped__:

import functools
def registrar(f):
@functools.wraps(f)
def envoltorio(*args, **kwargs):
return f(*args, **kwargs)
return envoltorio

No es cosmético: los frameworks que introspeccionan (FastAPI, pytest, Sphinx) leen esos atributos para construir rutas, recolectar tests y generar documentación. Un decorador sin wraps rompe los tres.

Para @reintentar(veces=3) hacen falta tres niveles: el que recibe el parámetro, el que recibe la función y el envoltorio.

def reintentar(veces=3):
def decorador(f):
@functools.wraps(f)
def envoltorio(*args, **kwargs):
for intento in range(veces):
try:
return f(*args, **kwargs)
except Exception:
if intento == veces - 1:
raise
return envoltorio
return decorador

La regla para no perderse: cuenta los paréntesis. @reintentar sin paréntesis recibe la función; @reintentar(veces=3) recibe el parámetro y devuelve el decorador. Confundirlos produce un TypeError en tiempo de importación.

Un decorador no tiene que recibir una función: puede recibir una clase y devolver una clase modificada. Es la forma de registrar subclases o inyectar métodos sin herencia:

def registrar_en(mapa):
def decorador(cls):
mapa[cls.__name__] = cls
return cls
return decorador
HANDLERS = {}
@registrar_en(HANDLERS)
class ManejadorPDF:
...

La diferencia con una metaclase es el orden: el decorador actúa después de que la clase exista, la metaclase durante su creación. Para registrar, el decorador basta y se lee mejor; __init_subclass__ es la otra alternativa moderna, y las metaclases quedan para cuando hay que cambiar cómo se construye la clase.

  • Si el comportamiento se aplica una vez. Un with o una llamada explícita se lee mejor que un decorador que hay que buscar tres líneas arriba.
  • Si el decorador oculta el flujo. Un @reintentar que captura excepciones puede convertir un fallo claro en un timeout silencioso.
  • Si el coste importa. Tres veces por llamada en un bucle cerrado; mide antes de envolver.
  • Si necesitas configurar por instancia. Un decorador es global para la clase; para variar por objeto, un atributo o un wrapper explícito.

Escribe un decorador @cronometrar que imprima cuánto tarda la función y devuelva su resultado. Debe funcionar con funciones de cualquier firma, conservar el nombre y no romper si la función lanza una excepción.

Solución
import functools
import time
def cronometrar(f):
@functools.wraps(f)
def envoltorio(*args, **kwargs):
inicio = time.perf_counter()
try:
return f(*args, **kwargs)
finally:
print(f"{f.__name__}: {time.perf_counter() - inicio:.4f} s")
return envoltorio

Tres detalles que separan esta solución de una que «funciona»:

  • functools.wraps conserva __name__, que es lo que se imprime.
  • El try/finally garantiza que se mide incluso si la función lanza. Sin él, el tiempo se pierde en el caso que más interesa depurar.
  • perf_counter() es monótono; time.time() puede saltar si el reloj del sistema se ajusta.

Comprobación con datos de ejemplo:

import io
from contextlib import redirect_stdout
@cronometrar
def suma(a, b=0):
"""Suma dos numeros."""
return a + b
@cronometrar
def falla():
raise ValueError("fallo")
salida = io.StringIO()
with redirect_stdout(salida):
resultado = suma(2, b=3)
print("resultado:", resultado, "| nombre:", suma.__name__, "| doc:", suma.__doc__)
print("imprime el nombre:", salida.getvalue().startswith("suma: "))
salida = io.StringIO()
with redirect_stdout(salida):
try:
falla()
except ValueError:
pass
print("mide aunque falle:", salida.getvalue().startswith("falla: "))
  • Ramalho, L. Fluent Python, 2ª ed. Capítulo 9: decoradores, clausuras y functools.wraps.
  • Lott, S. F. Modern Python Cookbook, 3ª ed. Capítulo 3.
  • Mediciones: mediciones/03-01-04-funciones.py.
  • 02 · Clausuras: el mecanismo que hace que envoltorio recuerde f.
  • 04 · functools: lru_cache y singledispatch son decoradores ya escritos.
  • 08 · Context managers: la otra forma de envolver código, sin cambiar la firma.