10

Introducción

Para elabrorar una respuesta a una pregunta de StackOverflow en Español que, desgraciadamente, fue finalmente borrada por el OP, estuve un rato investigando en la programación de decoradores Python y en particular en uno que fuera lo bastante flexible para adaptarse a una situación especialmente compleja.

Aunque la pregunta fue borrada, creo que lo que aprendí elaborando la respuesta puede ser útil a alguien más y me parece una pena que se pierda, así que replanteo aquí la pregunta, ligeramente modificada para no perjudicar al OP que hizo la pregunta original y la borró.

Se trata de implementar un decorador que pueda ser utilizado para que la función decorada pueda validar si ha recibido o no ciertos parámetros en un diccionario.

Por ejemplo, esta sería la función que recibe el diccionario:

def funcion_ejemplo(data={}, prefijo="<div>", sufijo="</div>"):
  return f"{prefijo}{data['item']} x {data['cantidad']}{sufijo}"

Que se podría invocar por ejemplo así:

cadena = funcion_ejemplo({'item': 'tornillo', 'cantidad': 6})

y produciría la cadena "<div>tornillo x 6</div>".

Naturalmente si a esta función no se le pasa el diccionario correcto (es decir, uno que no tenga el campo "item" o el campo "cantidad", la función romperá. En un caso general podría dar incluso resultados incorrectos. Queremos añadir a la función código que verifique si ha recibido los datos correctos y en caso contrario genere una excepción ValueError. Para este ejemplo particular esa validación se haría así:

  # ...
  for campo in ["item", "cantidad"]:
       if campo not in data or not data[campo]:  # (el campo existe pero viene vacío)
          raise(ValueError(f"Falta el campo {campo} en el diccionario"))

Se trataría ahora de delegar ese trabajo en un decorador que podemos llamar required_data de modo que pueda usarse así:

@required_data("item", "cantidad")
def funcion_ejemplo(data={}, prefijo="<div>", sufijo="</div>"):
  return f"{prefijo}{data['item']} x {data['cantidad']}{sufijo}"

¿Cómo se programaría un decorador así?

1 respuesta 1

9

El decorador que se pide es muy complejo por varias razones:

  • Es un decorador que recibe parámetros. Esto de por sí ya añade una complejidad conceptual importante, porque el decorador debe definir una función interna que al ser ejecutada devuelva a su vez un decorador, por lo que esa función interna deberá definir a su vez otra función interna, que será el decorador final.
  • El número de parámetros a recibir por el decorador es variable. En el ejemplo son dos: "item", "cantidad", pero cabe suponer que pueda recibir cualquier otra cantidad de campos a validar.
  • La función que se quiere decorar tiene valores por defecto entre sus parámetros, lo que complica la implementación del wrapper.

Hacer un buen decorador robusto y genérico que pueda copar con todo esto es complicado y el resultado necesariamente feo y bastante ilegible. Así que vamos por pasos.

Versión inicial simplista

Vamos a suponer de momento que siempre que se llame a la función una vez decorada se le va a pasar el parámetro data. Eso nos libera del problema de que se pueda invocar así simplemente con funcion_ejemplo(), lo que de momento facilitará la implementación del decorador.

En este caso el decorador que se busca podría ser como sigue (he incluido comentarios para tratar de explicar --y explicarme-- la complejidad):

def required_data(*args):

  # Este es el wrapper que recibe como parámetro la función a decorar
  def _wrapper(f):
    # Dentro hay otro decorador
    # Este es el código que se ejecutará al llamar a la funcion decorada
    def verify_and_call(*inner_args):
      # *inner_args son los parámetros
      req_data = args          # Tomamos del closure ("item", "cantidad")
      data = inner_args[0]     # Sacar el primer parámetro que se le pasa a f
      # Realizar la validación
      for d in req_data:
        if d not in data or not data[d]:
          raise(ValueError(f"Falta el campo '{d}' en el diccionario"))

      # Si la validación pasa, podemos invocar a la función f y pasarle los
      # mismos parámetros, retornando el resultado que devuelva f
      return f(*inner_args)

    # El _wrapper retorna la función que acabamos de definir
    return verify_and_call

  # El decorador retorna el _wrapper
  return _wrapper

Ejemplo de uso:

@required_data("item", "cantidad")
def funcion_ejemplo(data={}, prefijo="<div>", sufijo="</div>"):
  "La función puede tener una documentación en forma de docstring"
  return f"{prefijo}{data['item']} x {data['cantidad']}{sufijo}"

Demostración de que funciona:

>>> item1 = {"item": "tornillo", "cantidad": 6}
>>> item2 = {"item": "tuerca" }  # Falta cantidad, es erróneo
>>> funcion_ejemplo(item1)
'<div>tornillo x 6</div>'
>>> funcion_ejemplo(item2)
Traceback (most recent call last)
[...]
ValueError: Falta el campo 'cantidad' en el diccionario

Sin embargo, si no le pasamos parámetros falla de una forma rara:

>>> funcion_ejemplo()
Traceback (most recent call last)
[...]
---> 10       data = inner_args[0]     # Sacar el parámetro que se le pasa a f

IndexError: tuple index out of range

Efectivamente, al no pasarle parámetro *inner_args llega vacío, y el intento de acceder a su elemento [0] produce una excepción.

Por otro lado tampoco funciona bien si le pasamos el parámetro por nombre:

>>> funcion_ejemplo(data=item1)
Traceback (most recent call last)
----> 1 funcion_ejemplo(data=person1)

TypeError: verify_and_call() got an unexpected keyword argument 'data'

Efectivamente lo que ocurre ahora es que al haber definido verify_and_call() de modo que recibe solo parámetros posicionales (*inner_args), no nos deja pasarle parámetros con nombre.

Podríamos pensar en arreglarlo añadiéndole otro parámetro **kwargs, pero seguiríamos en problemas porque en todo caso el parámetro data no estaría en inner_args[0] como la función supone.

Segunda versión, manejando parámetros posicionales o con nombre

Si añadimos a verify_and_call() la posibilidad de recibir **kwargs, entonces puede que data esté en *inner_args si se pasó por posición, o en **kwargs si se pasó por nombre. De modo que el código debe buscar en ambos sitios:

def required_data(*args):

  # Este es el wrapper que recibe como parámetro la función a decorar
  def _wrapper(f):
    # Dentro hay otro decorador
    # Este es el código que se ejecutará al llamar a la funcion decorada
    def verify_and_call(*inner_args, **kwargs):
      # *inner_args son los parámetros
      req_data = args          # Tomamos del closure ("item", "cantidad")
      if "data" in kwargs:
        data = kwargs["data"]
      elif len(inner_args)>0:
        data = inner_args[0]
      else:
        raise(ValueError(f"Falta el parámetro data"))
      # Realizar la validación
      for d in req_data:
        if d not in data or not data[d]:
          raise(ValueError(f"Falta el campo '{d}' en el diccionario"))

      # Si la validación pasa, podemos invocar a la función f y pasarle los
      # mismos parámetros, retornando el resultado que devuelva f
      return f(*inner_args, **kwargs)

    # El _wrapper retorna la función que acabamos de decfinir
    return verify_and_call

  # El decorador retorna el _wrapper
  return _wrapper

Observa cómo se mira si "data" está en kwargs y si no se intenta tomar de inner_args y si tampoco está se eleva una excepción. Observa también cómo en la llamada a f() se le pasa también **kwargs por si es ahí donde venía data.

Ahora ya funciona con parámetros con nombre, o posicionales:

>>> funcion_ejemplo(item1)
'<div>tornillo x 6</div>'
>>> funcion_ejemplo(data=item1)
'<div>tornillo x 6</div>'

pero sigue fallando si no pasamos parámetros (aunque esta vez es porque elevamos a propósito una excepción señalándolo):

>>> funcion_ejemplo()
Traceback (most recent call last)
[...]
ValueError: Falta el parámetro data

Esto está bastante mejor, pero nos impide decorar una función que reciba un parámetro por defecto, como este:

@required_data("item", "cantidad")
def funcion_ejemplo(data={"item": "noname", "cantidad": 1}, prefijo="<div>", sufijo="</div>"):
  "La función puede tener una documentación en forma de docstring"
  return f"{prefijo}{data['item']} x {data['cantidad']}{sufijo}"

Aquí estamos pasando como valor por defecto a data un diccionario que debería validar correctamente pues tiene "item" y "cantidad", pero en realidad la validación ni siquiera llega a realizarse si llamamos funcion_ejemplo() sin parámetros, porque nuestro decorador espera un parámetro llamado data y no se lo estamos pasando.

Hay otro detalle menor, y es que al envolver la función de este modo se pierde el docstring de la función original:

>>> help(funcion_ejemplo)
Help on function verify_and_call in module __main__:

verify_and_call(*inner_args, **kwargs)

En vez de darnos la ayuda sobre la función funcion_ejemplo() nos está mostrando la de su envoltorio, verify_and_call()

Última versión, valores por defecto y docstrings

Para resolver el problema del docstring usaremos functools.wraps() que sirve para que se copie el prototipo y documentación de la función decorada a la función decoradora.

Para poder acceder al valor por defecto de data en la función decorada usaremos inspect.signature.

Esta es la versión final del decorador:

from functools import wraps
from inspect import signature

# Este es el decorador "externo". 
# args es la lista de parámetros que se le pasa al decorador
# por ejemplo ("name", "last_name")
def required_data(*args):

  # Este es el wrapper que recibe como parámetro la función a decorar
  def _wrapper(f):
    sig = signature(f)   # Obtener la declaración y lista de parámetros de f
    @wraps(f)     # Esto es para preservar nombre y docstring de la función decorada
      # Este es el código que se ejecutará al llamar a la funcion decorada
    def verify_and_call(*inner_args, **kwargs):
      # inner_args y kwargs son los parámetros con los que se invocará a la
      # función decorada
      req_data = args           # Tomamos del closure ("item", "cantidad")
      if inner_args:            # Sacamos el parámetro "data" de la función decorada
        data = inner_args[0]    # Pudo pasarsele como el primer argumento posicional
      elif "data" in kwargs:    # o como un argumento por nombre
        data = kwargs["data"]
      elif "data" in sig.parameters:    # o estar en la lista de valores por defecto de f
        data = sig.parameters["data"].default
      else:                     # o no estar en ningún sitio
        raise(ValueError(f"Falta el parámetro data"))
      # Realizar la validación
      for d in req_data:
        if d not in data or not data[d]:
          raise(ValueError(f"Falta el campo '{d}' en el diccionario"))

      # Si la validación pasa, podemos invocar a la función f y pasarle los
      # mismos parámetros, retornando el resultado que devuelva f
      return f(*inner_args, **kwargs)

    # El _wrapper retorna la función que acabamos de decfinir
    return verify_and_call

  # El decorador retorna el _wrapper
  return _wrapper

Se usa exactamente igual que los anteriores:

@required_data("item", "cantidad")
def funcion_ejemplo(data={}, prefijo="<div>", sufijo="</div>"):
  "La función puede tener una documentación en forma de docstring"
  return f"{prefijo}{data['item']} x {data['cantidad']}{sufijo}"

y podemos comprobar que soporta ya todas las características deseadas:

>>> # No le paso parámetro, rompe porque el parámetro por defecto es {} que no tiene "item"
>>> funcion_ejemplo()
[...]
ValueError: Falta el campo 'item' en el diccionario


>>> # Parámetro por posicion y por nombre
>>> funcion_ejemplo(data=item1)
'<div>tornillo x 6</div>'
>>> funcion_ejemplo(item1)
'<div>tornillo x 6</div>'


>>> # La ayuda funciona
>>> help(funcion_ejemplo)
Help on function funcion_ejemplo in module __main__:

funcion_ejemplo(data={}, prefijo='<div>', sufijo='</div>')
    La función puede tener una documentación en forma de docstring

También funciona correctamente si decoramos una función que tiene en data un valor por defecto válido:

@required_data("item", "cantidad")
def funcion_ejemplo(data={"item": "noname", "cantidad": 1}, prefijo="<div>", sufijo="</div>"):
  "La función puede tener una documentación en forma de docstring"
  return f"{prefijo}{data['item']} x {data['cantidad']}{sufijo}"


>>> funcion_ejemplo()
'<div>noname x 1</div>'

Tu Respuesta

By clicking “Publica tu respuesta”, you agree to our terms of service and acknowledge you have read our privacy policy.

¿No es la respuesta que buscas? Examina otras preguntas con la etiqueta o formula tu propia pregunta.