Python - Decorators

A decorator is a callable that takes a callable as input and returns a callable. This is the general definition of a decorator. The callable in this definition can be a function or a class. In our initial discussion, we will talk about decorator functions that are used to decorate functions; we will talk about classes later on. So, for the time being, we can think of a decorator as a function that takes a function as input and returns a function.

Decorators are used to add some functionality to a function. They allow you to execute some extra code before or after the execution of a function. This extra work is done without making any changes to the source code of the function. So, by using a decorator we can extend the behavior of a function without actually modifying its code.

A decorator is a function that takes another function as an argument, decorates it with the extra functionality and gives you a decorated function as the result.

def func1():
    print('Hello world')
    print('Welcome to Python')

def my_decorator(fn):
    def wrapper():
        print('Hi … Starting execution')
        fn()
        print('Bye … finished executing\n')
    return wrapper

decorated_func1 = my_decorator(func1)

@my_decorator
def func3():
   print('Learning decorators')

The function func3 is decorated using the automated decoration syntax and so now we do not need to write the statement func3 = my_decorator(func3). The @ syntax automates this reassignment of the function name.

Decorator Example: Checking return values

Decorator Example: Checking argument values

Preserving metadata of a function after decoration

If we do not want the original function to lose its name, documentation and other attributes, even after decoration, then we can use the wraps function from the functools module. This wraps function is a decorator that copies the introspection details of a function to another function. We will apply this decorator to the wrapper function.

from functools import wraps

def trace(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        print(f'{fn.__name__} called')
        print(f'args : {args}  kwargs : {kwargs}' )
        result = fn(*args, **kwargs)
        print(f'Return value : {result}\n')      
        return result

    return wrapper

This wraps decorator is little different, it is a decorator that takes an argument. We will see such decorators in the next section. We send function fn as argument to this wrapper function. So now all the important metadata of fn will be copied in the wrapper function.

General template for writing a decorator

from functools import wraps

def decorator_name(fn):
     @wraps(fn)
     def wrapper(*args, **kwargs):
        #Place code that has to be executed before function call 
        result = fn(*args, **kwargs)
        #Place code that has to be executed after function call 
        return result

     return wrapper

General template for writing a decorator factory

from functools import wraps

def decorator_name(parameter1, parameter2, …):
   def actual_decorator(fn):
     @wraps(fn)
     def wrapper(*args, **kwargs):
        #Place code that has to be executed before function call 
        result = fn(*args, **kwargs)
        #Place code that has to be executed after function call 
        return result

      return wrapper

   return actual_decorator

Applying decorators to imported functions

We can even apply our own decorators to the functions that we import from standard library or third-party packages. However, we cannot use the @ syntax for these functions.

from math import factorial
from random import randint


def trace(fn):
    def wrapper(*args, **kwargs):
        print(f'{fn.__name__} called')
        print(f'args : {args}  kwargs : {kwargs}' )
        result = fn(*args, **kwargs)
        print(f'Return value : {result}\n')      

        return result

    return wrapper


factorial = trace(factorial)
randint = trace(randint)
factorial(3)
randint(5, 50)