Decorator functions are software design patterns. They dynamically alter the functionality of a function, method, or class without having to directly use subclasses or change the source code of the decorated function. When used correctly, decorators can become powerful tools in the development process. This topic covers implementation and applications of decorator functions in Python.
def decorator_function(f): pass # defines a decorator named decorator_function
def decorated_function(): pass # the function is now wrapped (decorated by) decorator_function
decorated_function = decorator_function(decorated_function) # this is equivalent to using the syntactic sugar
|f||The function to be decorated (wrapped)|
Decorators augment the behavior of other functions or methods. Any function that takes a function as a parameter and returns an augmented function can be used as a decorator.
@-notation is syntactic sugar that is equivalent to the following:
It is important to bear this in mind in order to understand how the decorators work. This "unsugared" syntax makes it clear why the decorator function takes a function as an argument, and why it should return another function. It also demonstrates what would happen if you don't return a function:
Thus, we usually define a new function inside the decorator and return it. This new function would first do something that it needs to do, then call the original function, and finally process the return value. Consider this simple decorator function that prints the arguments that the original function receives, then calls it.
Create singleton class with a decorator
A singleton is a pattern that restricts the instantiation of a class to one instance/object. Using a decorator, we can define a class as a singleton by forcing the class to either return an existing instance of the class or create a new instance (if it doesn't exist).
This decorator can be added to any class declaration and will make sure that at most one instance of the class is created. Any subsequent calls will return the already existing class instance.
So it doesn't matter whether you refer to the class instance via your local variable or whether you create another "instance", you always get the same object.
As mentioned in the introduction, a decorator is a function that can be applied to another function to augment its behavior. The syntactic sugar is equivalent to the following:
my_func = decorator(my_func). But what if the
decorator was instead a class? The syntax would still work, except that now
my_func gets replaced with an instance of the
decorator class. If this class implements the
__call__() magic method, then it would still be possible to use
my_func as if it was a function:
Note that a function decorated with a class decorator will no longer be considered a "function" from type-checking perspective:
For decorating methods you need to define an additional
Inside the decorator.
Class Decorators only produce one instance for a specific function so decorating a method with a class decorator will share the same decorator between all instances of that class:
Decorator with arguments (decorator factory)
A decorator takes just one argument: the function to be decorated. There is no way to pass other arguments.
But additional arguments are often desired. The trick is then to make a function which takes arbitrary arguments and returns a decorator.
The decorator wants to tell you: Hello World
With such decorator factories you must call the decorator with a pair of parentheses:
TypeError: decorator() missing 1 required positional argument: 'func'
Inside the decorator with arguments (10,)
Making a decorator look like the decorated function
Decorators normally strip function metadata as they aren't the same. This can cause problems when using meta-programming to dynamically access function metadata. Metadata also includes function's docstrings and its name.
functools.wraps makes the decorated function look like the original function by copying several attributes to the wrapper function.
The two methods of wrapping a decorator are achieving the same thing in hiding that the original function has been decorated. There is no reason to prefer the function version to the class version unless you're already using one over the other.
As a function
As a class
'Docstring of test.'