Most decorators don’t make assumptions about the decorated function’s signature.
This is why they’re usually written with *args, **kwargs, like this:
def timed(func):
@wraps(func)
def timed_version(*args, **kwargs):
start = datetime.now()
result = func(*args, **kwargs)
print 'that took', datetime.now() - start
return result
return timed_version
Those can be used on any function, because the *args, **kwargs can match any pattern of
arguments. Sometimes though, the decorator needs access to one of the function’s arguments. For example the following decorator guards a Django view to check for parameters:
def requires_POST(*param_names):
'''enforces that a view be called with specific post params'''
def check_params(view_func):
@wraps(view_func)
def wrapper(*args, **kwargs):
request = kwargs['request'] # assuming request is always passed as keyword argument
for param in param_names:
if param not in request.POST:
return ParamNotFoundResponse(param)
return view_func(*args, **kwargs)
return wrapper
return check_params
This works okay, but we are depending on the fact that Django sends the request parameter as a keyword argument. We could make this more robust by doing something like kwargs.get('request', args[0]), but that has it’s own problem. Specifically, we’re assuming that request is the first parameter. (That assumption wouldn’t be true for a class-based-view, because the first parameter would be self.)
Also, we don’t just write decorators for views. I recently wrote a decorator that needs access to an org_id variable passed to the decorated function. Sometimes it’s passed directly, but sometimes it’s wrapped inside the session dictionary and the session is what’s passed. This sounds like a headache of searching kwargs or trying to assume the order parameters are passed in order to get our hands on the org_id. Just for the sake of completeness, here’s what that might look like:
def find_org_id(args, kwargs):
if 'org_id' in kwargs:
org_id = kwargs['org_id']
elif 'session' in kwargs:
org_id = kwargs['session']['org_id']
else:
# uhh, I dunno, I guess we start looking through
# args, trying to find one that looks like a session?
for arg in args:
if isinstance(arg, django.contrib.sessions.backends.db.SessionStore):
org_id = arg['org_id']
break
else:
# welll, dang. Let's just assume the first that's a string is
# the org_id I guess?
for arg in args:
if isinstance(arg, basestring):
org_id = args['org_id']
break
else:
# Crap. I don't even know.
raise RuntimeError("It doesn't look like this function take an org_id or a session.")
Ugh. That’s just terrible. I did warn you. Luckily, there’s a better way.
inspect.getcallargs(func, *args, **kwargs) returns a dictionary telling you what variables would be bound if you called func with *args, **kwargs. This is so much better than trying to guess or assume the order of parameters, or forcing the callers to use always use keyword arguments. We can say:
def find_org_id(func, args, kwargs):
callargs = inspect.getcallargs(func, *args, **kwargs)
if 'org_id' in callargs:
return callargs['org_id']
elif 'session' in callargs:
return callargs['session']['org_id']
raise RuntimeError('{} not called with org_id or session'.format(func.__name__))
What’s more, we can use another function in the inspect module to statically ensure that this function expects either session or org_id. By statically, I mean that we can check when the function being decorated is defined, at import-time, rather than when it’s called:
def the_decorator(func):
argspec = inspect.getargspec(func)
assert 'org_id' in argspec.args or 'session' in argspec.args, \
"the_decorator can only decorate functions that are passed an org_id or a session."
def decorated(*args, **kwargs):
org_id = find_org_id(func, args, kwargs)
# Do whatever you needed to do with the org id
return func(*args, **kwargs)
return decorated