Image for post Decoradores en Python: Potenciando tu Código con Funcionalidad Reutilizable y Elegante

Decoradores en Python: Potenciando tu Código con Funcionalidad Reutilizable y Elegante

Escrito por Sergio Márquez

Contexto del Problema

Como desarrolladores, a menudo nos encontramos con la necesidad de añadir funcionalidades "transversales" a múltiples partes de nuestro código. Piensa en tareas como registrar el tiempo de ejecución de una función, verificar permisos antes de ejecutar una operación, o simplemente añadir un log cada vez que una función es llamada. Si implementamos estas funcionalidades directamente dentro de cada función, nuestro código se vuelve repetitivo, difícil de mantener y propenso a errores. Imagina tener que copiar y pegar el mismo bloque de código de logging en diez funciones diferentes; si necesitas cambiar algo en el logging, tendrías que modificar diez lugares distintos.

Aquí es donde los decoradores de Python entran en juego. Son una herramienta poderosa y elegante que nos permite modificar o extender el comportamiento de funciones o métodos sin alterar su código fuente directamente. Nos ayudan a mantener nuestro código DRY (Don't Repeat Yourself), más legible y modular, encapsulando la lógica transversal en un solo lugar.

Conceptos Clave

Antes de sumergirnos en la implementación, es fundamental entender algunos conceptos básicos de Python que hacen posibles los decoradores.

Funciones de Primera Clase

En Python, las funciones son "ciudadanos de primera clase". Esto significa que pueden ser tratadas como cualquier otra variable: puedes asignarlas a otras variables, pasarlas como argumentos a otras funciones y devolverlas como resultado de otras funciones. Esta flexibilidad es la piedra angular de los decoradores.


def saludar(nombre):
    return f"Hola, {nombre}"

# Asignar una función a una variable
mi_saludo = saludar
print(mi_saludo("Mundo"))

# Pasar una función como argumento
def ejecutar_funcion(func, arg):
    return func(arg)

print(ejecutar_funcion(saludar, "Python"))

Clausuras (Closures)

Una clausura es una función interna que recuerda y tiene acceso al entorno (variables locales) en el que fue creada, incluso después de que la función externa haya terminado de ejecutarse. Las clausuras son esenciales para los decoradores porque permiten que la función "envoltura" (wrapper) que devuelve el decorador siga teniendo acceso a la función original que está decorando, así como a cualquier otra variable definida en el ámbito del decorador.


def crear_multiplicador(factor):
    def multiplicador(numero):
        return numero * factor
    return multiplicador

multiplicar_por_5 = crear_multiplicador(5)
multiplicar_por_10 = crear_multiplicador(10)

print(multiplicar_por_5(3)) # Salida: 15
print(multiplicar_por_10(3)) # Salida: 30

En este ejemplo, multiplicador es una clausura que "recuerda" el valor de factor incluso después de que crear_multiplicador ha terminado su ejecución.

¿Qué es un Decorador?

Un decorador es, en esencia, una función que toma otra función como argumento, añade alguna funcionalidad y devuelve una nueva función (o la misma modificada). La sintaxis @ es simplemente "azúcar sintáctico" para aplicar un decorador.

Sintaxis @

La sintaxis @nombre_decorador colocada justo encima de la definición de una función es equivalente a:


def mi_funcion():
    pass

mi_funcion = nombre_decorador(mi_funcion)

Esto hace que el código sea mucho más legible y declarativo.

Implementación Paso a Paso

1. Un Decorador Simple (sin argumentos)

Comencemos con el ejemplo más básico: un decorador que simplemente imprime un mensaje antes y después de ejecutar la función decorada.


def mi_primer_decorador(func):
    def envoltura():
        print("¡Algo está a punto de suceder!")
        func()
        print("¡Algo acaba de suceder!")
    return envoltura

@mi_primer_decorador
def decir_hola():
    print("Hola mundo")

decir_hola()

Explicación:

  • mi_primer_decorador es la función decoradora. Toma func (la función a decorar) como argumento.
  • Dentro de mi_primer_decorador, definimos una función anidada llamada envoltura. Esta es la clausura que mencionamos antes.
  • envoltura contiene la lógica adicional (los print) y llama a la función original func().
  • Finalmente, mi_primer_decorador devuelve la función envoltura.
  • Cuando usamos @mi_primer_decorador sobre decir_hola, lo que realmente sucede es que decir_hola se redefine como el resultado de mi_primer_decorador(decir_hola). Así, cuando llamamos a decir_hola(), en realidad estamos llamando a la función envoltura devuelta por el decorador.

2. Manejando Argumentos en la Función Decorada

La mayoría de las funciones toman argumentos. Nuestro decorador debe ser capaz de manejar esto. Usaremos *args y **kwargs para capturar cualquier número de argumentos posicionales y de palabra clave.


def decorador_con_args(func):
    def envoltura(*args, **kwargs):
        print(f"Llamando a '{func.__name__}' con args: {args}, kwargs: {kwargs}")
        resultado = func(*args, **kwargs)
        print(f"'{func.__name__}' ha terminado. Resultado: {resultado}")
        return resultado
    return envoltura

@decorador_con_args
def sumar(a, b):
    return a + b

@decorador_con_args
def saludar_personalizado(nombre, saludo="Hola"):
    return f"{saludo}, {nombre}"

print(sumar(5, 3))
print(saludar_personalizado("Ana", saludo="Buenos días"))

3. Preservando Metadatos con functools.wraps

Un problema común con los decoradores es que la función envoltura reemplaza los metadatos de la función original (como su nombre, docstring, módulo, etc.). Esto puede dificultar la depuración y el uso de herramientas de introspección. El módulo functools de Python nos proporciona @wraps para solucionar esto.


import functools

def mi_decorador_inteligente(func):
    @functools.wraps(func)
    def envoltura(*args, **kwargs):
        """Esta es la función envoltura."""
        print(f"Ejecutando {func.__name__}...")
        resultado = func(*args, **kwargs)
        print(f"{func.__name__} finalizado.")
        return resultado
    return envoltura

@mi_decorador_inteligente
def funcion_original(x, y):
    """Esta es la docstring de la función original."""
    return x * y

print(funcion_original(2, 4))
print(f"Nombre de la función: {funcion_original.__name__}")
print(f"Docstring de la función: {funcion_original.__doc__}")

Sin @functools.wraps(func), funcion_original.__name__ sería 'envoltura' y funcion_original.__doc__ sería 'Esta es la función envoltura.'. Con @wraps, se copian los metadatos de la función original, lo que es una buena práctica.

4. Decoradores con Argumentos

A veces, queremos que nuestro decorador acepte sus propios argumentos. Por ejemplo, un decorador de logging que permita especificar el nivel de log. Para lograr esto, necesitamos una capa adicional de anidamiento.


import functools
import os

def log_nivel(nivel_minimo="INFO"):
    """Decorador que registra la llamada a una función si el nivel de log es suficiente."""
    def decorador(func):
        @functools.wraps(func)
        def envoltura(*args, **kwargs):
            # Simulación de un nivel de log global desde una variable de entorno
            # En un caso real, usarías una librería de logging como `logging`
            nivel_actual_str = os.getenv("APP_LOG_LEVEL", "INFO").upper()
            niveles = {"DEBUG": 0, "INFO": 1, "WARNING": 2, "ERROR": 3, "CRITICAL": 4}
            
            if niveles.get(nivel_actual_str, 1) <= niveles.get(nivel_minimo.upper(), 1):
                print(f"[{nivel_minimo.upper()}] Llamando a '{func.__name__}' con args: {args}, kwargs: {kwargs}")
            
            resultado = func(*args, **kwargs)
            
            if niveles.get(nivel_actual_str, 1) <= niveles.get(nivel_minimo.upper(), 1):
                print(f"[{nivel_minimo.upper()}] '{func.__name__}' finalizado. Resultado: {resultado}")
            
            return resultado
        return envoltura
    return decorador

# Ejemplo de uso con diferentes niveles de log

@log_nivel(nivel_minimo="DEBUG")
def procesar_datos_sensibles(data):
    return f"Datos procesados: {data.upper()}"

@log_nivel(nivel_minimo="INFO")
def generar_reporte(mes):
    return f"Reporte de {mes} generado."

@log_nivel(nivel_minimo="ERROR")
def fallar_criticamente():
    raise ValueError("¡Error crítico!")

print("\n--- Ejecución con APP_LOG_LEVEL=INFO ---")
os.environ["APP_LOG_LEVEL"] = "INFO"
print(procesar_datos_sensibles("secreto"))
print(generar_reporte("Noviembre"))
try:
    fallar_criticamente()
except ValueError as e:
    print(f"Capturado: {e}")

print("\n--- Ejecución con APP_LOG_LEVEL=DEBUG ---")
os.environ["APP_LOG_LEVEL"] = "DEBUG"
print(procesar_datos_sensibles("secreto"))
print(generar_reporte("Diciembre"))

# Limpiar variable de entorno para otras pruebas si es necesario
del os.environ["APP_LOG_LEVEL"]

Explicación:

  • log_nivel es la función externa que toma los argumentos del decorador (nivel_minimo).
  • Devuelve decorador, que es la función que toma la función a decorar (func).
  • decorador a su vez devuelve envoltura, que es la función que realmente reemplaza a la original y contiene la lógica del decorador, teniendo acceso a nivel_minimo (gracias a la clausura) y a los argumentos de la función original.
  • Hemos incluido un ejemplo de cómo podrías usar una variable de entorno (APP_LOG_LEVEL) para controlar el comportamiento del decorador, siguiendo las buenas prácticas de configuración.

Mini Proyecto / Aplicación Sencilla

Vamos a aplicar lo aprendido para crear un conjunto de decoradores útiles que podrías usar en tus propios proyectos.

1. Decorador para Medir el Tiempo de Ejecución

Útil para perfilar funciones y entender dónde se gasta el tiempo.


import time
import functools

def medir_tiempo(func):
    @functools.wraps(func)
    def envoltura(*args, **kwargs):
        inicio = time.perf_counter()
        resultado = func(*args, **kwargs)
        fin = time.perf_counter()
        tiempo_ejecucion = fin - inicio
        print(f"'{func.__name__}' ejecutado en {tiempo_ejecucion:.4f} segundos.")
        return resultado
    return envoltura

@medir_tiempo
def calcular_fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

@medir_tiempo
def simular_operacion_larga(duracion):
    time.sleep(duracion)
    return "Operación completada"

print(calcular_fibonacci(10000))
print(simular_operacion_larga(0.5))

2. Decorador para Reintentos Automáticos

Ideal para operaciones que pueden fallar temporalmente, como llamadas a APIs externas o conexiones a bases de datos.


import time
import functools
import random

def reintentar(num_reintentos=3, delay_segundos=1):
    def decorador(func):
        @functools.wraps(func)
        def envoltura(*args, **kwargs):
            for intento in range(1, num_reintentos + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    print(f"Intento {intento} de {num_reintentos} fallido para '{func.__name__}': {e}")
                    if intento < num_reintentos:
                        time.sleep(delay_segundos)
            raise Exception(f"'{func.__name__}' falló después de {num_reintentos} reintentos.")
        return envoltura
    return decorador

fallos_restantes = 2 # Simula que la función fallará 2 veces antes de tener éxito

@reintentar(num_reintentos=3, delay_segundos=0.1)
def operacion_inestable():
    global fallos_restantes
    if fallos_restantes > 0:
        fallos_restantes -= 1
        raise ConnectionError("Conexión perdida temporalmente")
    return "¡Operación exitosa!"

print(operacion_inestable())

# Ejemplo de una función que siempre falla
@reintentar(num_reintentos=2, delay_segundos=0.05)
def operacion_siempre_falla():
    raise ValueError("¡Siempre fallo!")

try:
    operacion_siempre_falla()
except Exception as e:
    print(f"Capturado: {e}")

3. Decorador de Autenticación Simple

Un ejemplo básico para controlar el acceso a funciones.


import functools

def requiere_autenticacion(rol_requerido="usuario"):
    def decorador(func):
        @functools.wraps(func)
        def envoltura(usuario, *args, **kwargs):
            # En un sistema real, 'usuario' sería un objeto con roles y credenciales
            # Aquí, simplificamos asumiendo que 'usuario' es un diccionario con una clave 'rol'
            if not isinstance(usuario, dict) or "rol" not in usuario:
                raise ValueError("Objeto de usuario inválido.")

            if usuario["rol"] == "admin": # Los admins siempre tienen acceso
                print(f"Admin '{usuario['nombre']}' accediendo a '{func.__name__}'.")
                return func(usuario, *args, **kwargs)
            
            if usuario["rol"] == rol_requerido:
                print(f"Usuario '{usuario['nombre']}' con rol '{usuario['rol']}' accediendo a '{func.__name__}'.")
                return func(usuario, *args, **kwargs)
            else:
                raise PermissionError(f"Acceso denegado para el usuario '{usuario['nombre']}'. Rol '{rol_requerido}' requerido.")
        return envoltura
    return decorador

@requiere_autenticacion(rol_requerido="editor")
def editar_articulo(usuario, articulo_id, contenido):
    return f"Artículo {articulo_id} editado por {usuario['nombre']}. Nuevo contenido: {contenido[:20]}..."

@requiere_autenticacion(rol_requerido="admin")
def eliminar_usuario(usuario, usuario_id):
    return f"Usuario {usuario_id} eliminado por {usuario['nombre']}."

usuario_admin = {"nombre": "Alice", "rol": "admin"}
usuario_editor = {"nombre": "Bob", "rol": "editor"}
usuario_lector = {"nombre": "Charlie", "rol": "lector"}

print(editar_articulo(usuario_editor, 101, "Nuevo contenido del artículo..."))
print(eliminar_usuario(usuario_admin, 505))

try:
    editar_articulo(usuario_lector, 102, "Intento de edición...")
except PermissionError as e:
    print(f"Error: {e}")

try:
    eliminar_usuario(usuario_editor, 506)
except PermissionError as e:
    print(f"Error: {e}")

Errores Comunes y Depuración

Aunque los decoradores son potentes, pueden ser una fuente de confusión si no se entienden bien. Aquí hay algunos errores comunes:

1. Olvidar functools.wraps

Como vimos, no usar @functools.wraps hará que la función decorada pierda su nombre original, docstring y otros metadatos. Esto puede complicar la depuración, la generación de documentación y el uso de herramientas de introspección. Siempre usa @functools.wraps(func) en tu función envoltura.

2. Confundir Decoradores con y sin Argumentos

La estructura de un decorador sin argumentos es de dos niveles de anidamiento (decorador -> envoltura). La de un decorador con argumentos es de tres niveles (función_configuradora -> decorador -> envoltura). Intentar pasar argumentos directamente a un decorador de dos niveles resultará en un TypeError porque el primer argumento que espera es la función a decorar, no tus argumentos.

3. Orden de los Decoradores

Cuando aplicas múltiples decoradores a una función, se aplican en el orden inverso al que se escriben, de abajo hacia arriba. Es decir, el decorador más cercano a la función se aplica primero, y el resultado de ese decorador es pasado al siguiente decorador hacia arriba.


@decorador_B
@decorador_A
def mi_funcion():
    pass

Esto es equivalente a mi_funcion = decorador_B(decorador_A(mi_funcion)). El orden importa, ya que cada decorador modifica la función que recibe antes de pasarla al siguiente.

4. Efectos Secundarios Inesperados

Un decorador modifica el comportamiento de una función. Si el decorador tiene efectos secundarios (ej. modifica variables globales, abre conexiones que no cierra), esto puede llevar a comportamientos inesperados en la función decorada. Asegúrate de que tus decoradores sean lo más puros y autocontenidos posible.

Aprendizaje Futuro / Próximos Pasos

Los decoradores son una característica fundamental de Python con muchas aplicaciones. Aquí hay algunas áreas para explorar a medida que profundices:

  • Decoradores de Clase: Así como puedes decorar funciones, también puedes decorar clases. Esto te permite modificar el comportamiento de una clase o sus métodos en el momento de su definición.
  • Decoradores como Clases: En lugar de una cadena de funciones anidadas, puedes implementar un decorador como una clase que implementa el método __call__. Esto puede ser útil para decoradores que necesitan mantener un estado.
  • Uso en Frameworks: Muchos frameworks populares de Python hacen un uso extensivo de decoradores. Por ejemplo, en Flask y FastAPI, usas decoradores para definir rutas (@app.route('/'), @app.get('/')). En Django, los decoradores se usan para permisos (@permission_required) o para marcar funciones como tareas asíncronas.
  • Creación de DSLs (Domain Specific Languages): Los decoradores pueden ser una herramienta poderosa para crear pequeños lenguajes específicos de dominio dentro de tu código Python, haciendo que ciertas tareas sean más declarativas y fáciles de entender.
  • functools.partial: Aunque no es un decorador en sí mismo, functools.partial es una función que te permite "congelar" algunos argumentos de una función, creando una nueva función con menos argumentos. Puede ser útil en escenarios relacionados con la programación funcional y la composición de funciones.

Dominar los decoradores te abrirá las puertas a escribir código Python más limpio, modular y potente. ¡Experimenta con ellos y verás cómo transforman tu forma de programar!

Volver al blog