End Point: Python decorator basics

Python decorators have been around since 2005, when they were included in the release of Python 2.4.1. A decorator is nothing more than syntax for passing a function to another function, or wrapping functions. Best put, a decorator is a function that takes a function as an argument and returns either the same function or some new callable. For example,

@foo
@bar
@baz
@qux
def f():
    pass

is shorthand for:

def f():
    pass
f = foo(bar(baz(qux(f))))

Say we have some functions we are debugging by printing out debug comments:

def mul(x, y):
    print __name__
    return x*y

def div(x, y):
    print __name__
    return x/y

The printing in the functions can be extracted out into a decorator like so:

def debug(f):            # debug decorator takes function f as parameter
    msg = f.__name__     # debug message to print later
    def wrapper(*args):  # wrapper function takes function f's parameters
        print msg        # print debug message
        return f(*args)  # call to original function
    return wrapper       # return the wrapper function, without calling it

Our functions get decorated with:

@debug
def mul(x, y):
    return x*y

@debug
def div(x, y):
    return x/y

Which again is just shorthand for:

def mul(x, y):
    return x*y
mul = debug(mul)

def div(x, y):
    return x/y
div = debug(div)

Looking at the definition of the debug function we see that debug(mul) returns wrapper, which becomes the new mul. When we now call mul(5, 2) we are really calling wrapper(5, 2). But how do subsequent calls to wrapper have access to the initial f parameter passed to debug and to the msg variable defined in debug? Closures. Taken from aaronasterling's response to this stackoverflow question, "A closure occurs when a function has access to a local variable from an enclosing scope that has finished its execution." You can read more about closures here, here, and here. So, at the moment that mul is decorated, debug(mul) is executed returning wrapper, which has access to the original mul function and to the msg variable, which is then set as the new mul.

By decorating, we remove code duplication and if the need to ever change the debug logic arises, we only need to do so in one place. Now, decorators with (non-optional) arguments get a bit trickier, but only because the syntax is a bit hard to grasp at first sight. Say that we want to pass the debug message as a parameter to the decorator like so:

@debug("Let's multiply!")
def mul(x, y)
    return x*y

Then the debug decorator would be:

def debug(msg):
    def actual_decorator(f):    # from here to
        def wrapper(*args):     # ...
            print msg           # ...
            return f(*args)     # ...
        return wrapper          # here, looks just like our debug decorator from above!
    return actual_decorator

A decorator with arguments should return a function that takes a function as an argument and returns either the same function or some new callable (what a mouthful, eh?). In other words, a decorator with arguments returns a decorator without arguments.

Looking at what the decorator syntax is shorthand for we can follow along as debug gets executed:

mul = debug("Let's multiply")(mul)

The debug function returns actual_decorator, to which we pass the mul function as the parameter, which then returns wrapper. So again, mul becomes wrapper which has access to msg and f because of closure.

What about decorators with optional arguments? That I'll leave for a future blog post :)