How Do Decorators Take Arguments?

When the decorator itself needs a setting of its own, such as a repeat count, a prefix, or a timeout, the nesting gets one level deeper. The reason is simple: the setting has to be captured before the function is wrapped, so there is an extra step in the middle.

The three levels each have their own job. The outermost level is the factory, and it receives the settings, such as a count of three. It returns the decorator. The middle level is the decorator itself, and it receives the function that is being decorated, and it returns the wrapper. The innermost level is the wrapper, and it receives the arguments of the real call, passes them on to the original function, and returns the result.

Why do you need three levels rather than two? Because the wrapper has to remember the configuration, and that configuration arrives one step before the wrapper is created. The factory captures it and hands it down through a closure, so by the time the decorated function is called, the setting is already fixed and cannot change.

The @ syntax hides the middle step from you. Writing @repeat(3) above a function does exactly the same thing as writing repeat(3)(func), because the decorator factory is called with the settings first, and the result of that call is then applied to the function.

If the decorator needs no settings at all, then the factory level is unnecessary and the two-level form is enough. The simple rule to remember is that the number of levels equals the number of things the decorator is given before the function arrives. The earlier questions in this topic covered the two-level form, and this answer adds the extra level that configuration requires.

Each level has a distinct job, and naming the levels clearly is what makes the pattern easy to read.

import functools


def with_prefix(prefix):        # 1. the factory takes the settings
    def decorator(func):        # 2. the decorator takes the function
        @functools.wraps(func)
        def wrapper(*args, **kwargs):   # 3. the wrapper takes the call
            return prefix + func(*args, **kwargs)
        return wrapper
    return decorator


@with_prefix('>> ')
def shout(text):
    return text.upper()


print(shout('hi'))       # >> HI

The output is >> HI. The comments in the snippet name the three levels for you, which is the factory that takes the settings, the decorator that takes the function, and the wrapper that takes the call.

Two details are worth pointing out. The @functools.wraps(func) line belongs on the wrapper, and func is in scope there because the decorator closed over it. The closure is also what makes the configuration stick, because prefix is captured on the way down and stays available to the wrapper long after with_prefix has already returned.

Notice also that the wrapper accepts *args and **kwargs. Without them, this decorator would only work on functions that take exactly one positional argument, and that is the usual mistake when you write your first decorator with arguments of its own.