Python in a Nutshell, 2nd Edition

Decorators

Due to the existence of descriptor types such as staticmethod and classmethod, covered in Class-Level Methods, which take as their argument a function object, Python somewhat frequently uses, within class bodies, idioms such as:

def f(cls, ...):
  ...definition of f snipped...
f = classmethod(f)

Having the call to classmethod occur textually after the def statement may decrease code readability because, while reading f’s definition, the reader of the code is not yet aware that f is destined to become a class method rather than an ordinary instance method. The code would be more readable if the mention of classmethod could be placed right before, rather than after, the def. Python 2.4 allows such placement, through the new syntax form known as decoration:

@classmethod
def f(cls, ...):
  ...definition of f snipped...

The @classmethod decoration must be immediately followed by a def statement and means that f=classmethod(f) executes right after the def statement (for whatever name f the def defines). More generally, @expression evaluates the expression (which must be a name, possibly qualified, or a call) and binds the result to an internal temporary name (say, _ _aux); any such decoration must be immediately followed by a def statement and means that f=_ _aux(f) executes right after the def statement (for whatever name f the def defines). The object bound to _ _aux is known as a decorator, and it’s said to decorate function f.

Decoration affords a handy shorthand for some higher-order ...