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>'