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.
En una línea
Sección titulada «En una línea»Un decorador recibe una función, devuelve otra, y ambas son objetos.
El mecanismo, sin azúcar
Sección titulada «El mecanismo, sin azúcar»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 @registrarsumar(2, 3) # imprime y devuelve 5Las 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.
El coste
Sección titulada «El coste»| 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.
functools.wraps: no lo olvides
Sección titulada «functools.wraps: no lo olvides»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 sumarfunctools.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 envoltorioNo 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.
Decoradores con parámetros
Sección titulada «Decoradores con parámetros»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 decoradorLa 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.
Decoradores de clase
Sección titulada «Decoradores de clase»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.
La trampa
Sección titulada «La trampa»Cuándo no aplica
Sección titulada «Cuándo no aplica»- Si el comportamiento se aplica una vez. Un
witho 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
@reintentarque 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.
Ejercicio
Sección titulada «Ejercicio»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 functoolsimport 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 envoltorioTres detalles que separan esta solución de una que «funciona»:
functools.wrapsconserva__name__, que es lo que se imprime.- El
try/finallygarantiza 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 iofrom contextlib import redirect_stdout
@cronometrardef suma(a, b=0): """Suma dos numeros.""" return a + b
@cronometrardef 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: passprint("mide aunque falle:", salida.getvalue().startswith("falla: "))Referencias
Sección titulada «Referencias»- 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.
Capítulos relacionados
Sección titulada «Capítulos relacionados»- 02 · Clausuras: el mecanismo que hace que
envoltoriorecuerdef. - 04 ·
functools:lru_cacheysingledispatchson decoradores ya escritos. - 08 · Context managers: la otra forma de envolver código, sin cambiar la firma.