Question

I’m new to Python, and stumped by this piece of code from the Boto project:

class SubdomainCallingFormat(_CallingFormat):
    @assert_case_insensitive
    def get_bucket_server(self, server, bucket):
        return '%s.%s' % (bucket, server)

def assert_case_insensitive(f):
    def wrapper(*args, **kwargs):
        if len(args) == 3 and not (args[2].islower() or args[2].isalnum()):
            raise BotoClientError("Bucket names cannot contain upper-case " \
            "characters when using either the sub-domain or virtual " \
        "hosting calling format.")
        return f(*args, **kwargs)
    return wrapper

Trying to understand what’s going on here.

1. What is the ‘@’ symbol in @assert_case_sensitive ?
2. What do the args *args, **kwargs mean?
3. What does ‘f‘ represent?

Thanks!

Answer 1

In this particular case assert_case_sensitive is a function wrapping function, otherwise known as a decorator.

A decorator takes an existing function and returns a different function. Usually it returns a new function that calls the original function in some way. In this case assert_case_insensitive always returns wrapper which is a function that’s defined within it who’s name is only known inside assert_case_insensitive.

When a function is declared in the body of another like that, the enclosed function is sort of created anew every time the outer function is called. This means the inner function has access to the variables from the function it was in.

This technique is called a closure, and Python’s support of closures is incomplete because the variables from the enclosing scopes cannot be modified. But that’s not terribly relevant to this question.

The goal of assert_case_insensitive is to enforce some conditions on the arguments to the functions it’s passed. It returns a new function that enforces those conditions and calls the original function. In order for assert_case_insensitive to be able to be used to wrap any function, it needs to work for functions with different numbers of arguments, and functions that have keyword arguments. This is where *args and **kargs come in.

An argument of the form *something gets a tuple of any remaining non-keyword (aka positional) arguments that are not accounted for by the previous positional arguments. An argument of the form **something gets a dictionary any remaining keyword arguments that are not accounted for by the previous positional arguments. Arguments of the form *something or **something must occur after all other arguments.

A similar syntax is used for calling functions with argument lists that aren’t know. An argument of the form *(iterable sequence) is turned into a series of positional arguments, and an argument of the form **(dictionary) is turned into a set of keyword arguments.

So wrapper is using these constructs so it can work very generally for any function. Decorators in general are expected to work for any function, so doing something like this is highly recommended when writing them.