Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Statements and Keywords

Python decorators

Reference for Python decorators: the @ syntax, writing function and class decorators, functools.wraps, decorators with arguments and stacking order.

A decorator is a callable that takes a function (or class) and returns a replacement, usually the same object wrapped with extra behavior. The @name line above a def or class is shorthand for rebinding the name to the result of calling the decorator.

Decorators are how Python adds logging, caching, access checks, registration and similar cross-cutting features without touching the body of the function. Several built-ins, such as @property, @staticmethod and @classmethod, are decorators.

Python
@decorator
def f(): ...

# means exactly:
def f(): ...
f = decorator(f)

Try it

Python Writing a decorator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Arguments, stacking and class decorators

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Syntax

Python
@decorator
def function(): ...

@decorator(arg1, arg2)
def function(): ...

@decorator
class Name: ...
Part Description
@decorator Any expression that evaluates to a callable taking one argument. Since Python 3.9 it may be any expression, for example @buttons[0].clicked.connect.
@decorator(args) A decorator factory: the call runs first and must return the real decorator.
Stacked decorators Applied from the bottom up: the one nearest the def wraps first.

Return value of a decorator: whatever it returns replaces the name. Return the original object (as register above does) to leave it untouched, or a wrapper to change its behavior.

Raises: whatever the decorator raises when it runs, which happens once, at definition time.

Usage notes

  • Use functools.wraps on the inner wrapper. It copies __name__, __doc__, __module__ and sets __wrapped__, so debuggers and help text still show the original function.
  • Three levels for arguments. @repeat(2) calls repeat(2), which returns the decorator, which receives the function and returns the wrapper.
  • Forget the return in the decorator and the decorated name becomes None. Forget to return the wrapper's result and every call returns None.
  • Run once at definition. The decorator body runs when the function is defined (import time); the wrapper runs on every call.
  • Class decorators receive the class and typically register it, add attributes or return a modified class. @dataclass is an example.
  • Methods. A wrapper that takes *args, **kwargs works on methods too, because self arrives as the first positional argument.
  • Decorating with classes. A class with __call__ can act as a decorator; its instances keep state between calls.
  • Order matters. With @a above @b, the result is a(b(f)); the outer decorator sees the inner wrapper.
  • Ready-made ones: functools.cache, functools.lru_cache, contextlib.contextmanager, abc.abstractmethod, typing.overload.