Python decorators

last modified July 6, 2020

Python decorators tutorial shows how to use decorator functions in Python.

Python functions are first-class citizens. This means that functions have equal status with other objects in Python. Functions can be assigned to variables, stored in collections, created and deleted dynamically, or passed as arguments.

A nested function, also called an inner function, is a function defined inside another function.

Python decorator

Python decorator extends and modifies the behavior of a callable without modifying the callable itself. Decorators are functions which decorate (or wrap) other functions and execute code before and after the wrapped function runs.

Python decorators are often used in logging, authentication and authorization, timing, and caching.

Python decorator example

In the next example, we create a simple decorator example.

enclose.py

#!/usr/bin/env python

def enclose(fun):

    def wrapper():

        print("***************************")
        fun()
        print("***************************")

    return wrapper

def myfun():
    print("myfun")

enc = enclose(myfun)
enc()

The enclose() function is a decorator which extends the decorated function by adding star symbols to its output.

def enclose(fun):
...

The enclose() function takes a function as a parameter.

def wrapper():

    print("***************************")
    fun()
    print("***************************")

return wrapper

The wrapper() decorates the passed function with stars. The wrapper function is returned.

def myfun():
    print("myfun")

This is a regular function to be decorated.

enc = enclose(myfun)
enc()

The myfun is passed to the enclose() function, in which it is extended. The wrapper function is returned and called.

$ ./enclose.py
***************************
myfun
***************************

This is the output. The decorator adds the stars before and after the output of the regular function.

Python decorator with @ symbol

Python allows to use the @ symbol to mark the method to be decorated with a decorator.

enclose2.py

#!/usr/bin/env python

def enclose(fun):

    def wrapper():

        print("***************************")
        fun()
        print("***************************")

    return wrapper

@enclose
def myfun():
    print("myfun")

myfun()

Functionally, the example is equivalent to the previous one. Only different syntax is used.

Decorating functions with parameters

The following examples show how to decorate functions which take parameters.

param.py

#!/usr/bin/env python

def enclose(fun):

    def wrapper(val):

        print("***************************")
        fun(val)
        print("***************************")

    return wrapper

@enclose
def myfun(val):
    print(f"myfun with {val}")

myfun('falcon')

In this code example, the regular function takes one argument.

params.py

#!/usr/bin/env python

def enclose(fun):

    def wrapper(*args, **kwargs):

        print("***************************")
        fun(*args, **kwargs)
        print("***************************")

    return wrapper

@enclose
def myfun(name, age):
    print(f'{name} is {age} years old')

myfun(name='Peter', age=32)
myfun('Roman', 29)

This example shows how to deal with variable number of parameters using the *args, **kwargs syntax.

Python decorator modify data

The decorator function can modify the data of the decorated function.

uppercase.py

#!/usr/bin/env python

def uppercase(fun):

    def wrapper():

        res = fun()
        modified = res.upper()

        return modified
    return wrapper


@uppercase
def gen_message():
    return 'Hello there!'

msg = gen_message()
print(msg)

The @uppercase decorator changes the returned text to uppercase.

def uppercase(fun):

    def wrapper():

        res = fun()
        modified = res.upper()

        return modified
    return wrapper

Inside the wrapper function the text is modified and returned.

$ ./uppercase.py
HELLO THERE!

This is the output.

Python multiple stacked decorators

It is possible to apply multiple decorators on a function.

multiple_decors.py

#!/usr/bin/env python

def strong(fun):

    def wrapper():
        return f'<strong>{fun()}</strong>'
    return wrapper

def em(fun):

    def wrapper():
        return f'<em>{fun()}</em>'

    return wrapper


@strong
@em
def message():
    return 'This is some message'


print(message())

In the example, we apply two HTML tags on a text.

$ ./multiple_decors.py
<strong><em>This is some message</em></strong>

This is the output.

Python decorator timing example

In the following example, we apply a timer decorator on a function.

timing.py

#!/usr/bin/env python

import time
import math

def timer(func):

    def wrapper(*args, **kwargs):

        begin = time.time()

        f = func(*args, **kwargs)

        end = time.time()
        print("Total time taken in : ", func.__name__, end - begin)

        return f

    return wrapper


@timer
def factorial(num):

    return math.factorial(num)

f = factorial(4580)
print(f)

The example calculates how long the factorial() function runs using a decorator.

begin = time.time()

Before the function is run, we get the start time.

end = time.time()
print("Total time taken in : ", func.__name__, end - begin)

After the function is run, we get the end time and print the difference.

The functools @wraps decorator

After applying the decorator function, the __name__, __doc__, and __module__ attributes of the original function are lost. This makes debugging awkward. To fix this, we can use the functool's @wraps decorator.

naming.py

#!/usr/bin/env python

from functools import wraps

def enclose(fun):

    @wraps(fun)
    def wrapper():
        '''This is wrapper function'''

        print("***************************")
        fun()
        print("***************************")

    return wrapper

@enclose
def myfun():
    '''this is myfun()''' 
    print("myfun")

myfun()

print(myfun.__name__)
print(myfun.__doc__)

In the example, we apply the @wraps decorator on the wrapper function. The name and the docstring of the original function (myfun) are kept.

$ ./naming.py
***************************
myfun
***************************
myfun
this is myfun()

This is the output.

Python class decorator

It is possible to use classes as decorators. For this, we need to implement the __call__ magic function.

counting_calls.py

#!/usr/bin/env python

import functools

class CountCalls:

    def __init__(self, fun):

        functools.update_wrapper(self, fun)
        self.fun = fun
        self.num_of_calls = 0

    def __call__(self, *args, **kwargs):

        self.num_of_calls += 1
        print(f"Call {self.num_of_calls} of {self.fun.__name__} fun")
        return self.fun(*args, **kwargs)

@CountCalls
def hello():
    print("Hello there!")

hello()
hello()
hello()

In the example, we use a class decorator to count the calls of a regular function.

def __init__(self, fun):

    functools.update_wrapper(self, fun)
    self.fun = fun
    self.num_of_calls = 0

We call the update_wrapper() function. It has the same purpose as the @wraps decorator; i.e. it keeps the metadata of the original function (__name__ or __doc__). We keep the reference to the original function and set the num_of_calls variable.

def __call__(self, *args, **kwargs):

    self.num_of_calls += 1
    print(f"Call {self.num_of_calls} of {self.fun.__name__} fun")
    return self.fun(*args, **kwargs)

We increase the num_of_calls variable, print a message, and call the original function, passing it possible arguments.

$ ./counting_calls.py
Call 1 of hello fun
Hello there!
Call 2 of hello fun
Hello there!
Call 3 of hello fun
Hello there!

This is the output.

Python @staticmethod decorator

Python has the @staticmethod built-in decorator, which creates a static method in Python class. A static method belongs to a class and is called without creating an instance.

static_method.py

#!/usr/bin/env python

class Math:

    @staticmethod
    def abs(x):
        
        if x < 0:
            return -x
        return x


print(Math.abs(3))
print(Math.abs(-3))

In the example, we create a static abs() method using the @staticmethod decorator. The method is called by specifying the class name and using the dot operator: Math.abs().

Flask decorators

Popular Python framework Flask uses decorators. For instance, the @app.route() is used to define routes.

app.py

#!/usr/bin/env python

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return 'Hello there!'

In the example, the hello() function is mapped to the root page using Flask's @app.route() decorator.

In this tutorial, we have worked with Python decorators.

List all Python tutorials.

Ebooks

Python decorators

Python decorator

Python decorator example

Python decorator with @ symbol

Decorating functions with parameters

Python decorator modify data

Python multiple stacked decorators

Python decorator timing example

The functools @wraps decorator

Python class decorator

Python @staticmethod decorator

Flask decorators