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.
@decorator def f(): ... # means exactly: def f(): ... f = decorator(f)
Try it
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.
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
@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.wrapson 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)callsrepeat(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 returnsNone. - 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.
@dataclassis an example. - Methods. A wrapper that takes
*args, **kwargsworks on methods too, becauseselfarrives 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
@aabove@b, the result isa(b(f)); the outer decorator sees the inner wrapper. - Ready-made ones:
functools.cache,functools.lru_cache,contextlib.contextmanager,abc.abstractmethod,typing.overload.