The Amazing Power of Decorators (Python Wonders — Ep 1)

Understand and master decorators in less than 10 minutes

Welcome to the first episode of this series. Without further talk, let’s get into it!

What are decorators?

Before everything else, what are decorators?

What are decorators?

Decorators, as the name suggests, are used to decorating a function or a method. Here decorate means change the behavior of the function. A decorator generally adds some functionality to a function.

A decorator generally adds some functionality to a function.

Even though these decorators are present in many programming languages, here I will focus on Python decorators. But the concept of decorating a function is not unique to Python.

The concept of decorating a function is not unique to Python.

Why do we need decorators?

Now that you know what is a decorator, you may be wondering.

What’s the point of having decorators? Why not just add the functionality inside of the function’s body? It would easier, no need to create a decorator, and it would make everything more clear, so that you know exactly what the function will do.

And yes, that’s true, but as you must know, the absolute goal in programming is to prevent repetition.

The absolute goal in programming is to prevent repetition.

For example, if you have 5 functions that at the start print the current time, and then do something else different for each one, why repeat yourself, and write 5 times the code to print the current time?

Else you could just a decorator that would decorate the functions and make them print the current time without needing to write it in each function. And that’s the whole point of decorators, add functionality to multiple functions without needing to rewrite it each time.

Add functionality to multiple functions without needing to rewrite it each time.

How to use decorators?

OK, now you understand what are decorators and how to use them, let’s dive into the more technical part.

In Python, decorators, are just functions, that take as input a function, and return the decorated function. For example, imagine you have a decorator ( print_current_time ), and you want to decorate a function, here is how you can do it:

def some_function(...):
    ...

some_function_decorated = print_current_time(some_function)

And now, if you call the some_function_decorated , the first thing the function is going to do is print the current time.

Or if you need to call only once the decorated function, you don’t need to store it, you can just call it right away:

def some_function(...):
    ...

print_current_time(some_function)(...)

This syntax of calling a function and then calling the result may not be very intuitive, but it’s completely valid in Python.

How to create decorators?

You can use decorators without knowing how to create ones, but sometimes you will see that you could prevent a lot of repetitions and feel the need to create your own decorator. So let’s do it.

We will create a decorator that measures the time taken by the decorated function to execute, and then that print it.

First, and before implementing our timer, we need to understand the way of creating decorators.

Decorators are functions, that take as first argument a function, and that return another function. In Python, there are two ways to create functions the first is lambda functions, but they aren’t really good to define complex functions. The second way is using the “def” keyword. So inside of our decorator, we will need to define a function with “def”. And then we will return this function, it will look something like this:

def my_decorator( func ):
    def decorated_func():
        ...
    return decorated_func

Inside of decorated_func , we will need to call func to execute the original function. But we can add more code than just the func call.

def my_decorator( func ):
    def decorated_func():
        ...
        func()
        ...
    return decorated_func

Good! But what if func returns a value? Our decorated_func won’t return it, so we need to return the return value of func .

def my_decorator( func ):
    def decorated_func():
        ...
        result = func()
        ...
        return result
    return decorated_func

That’s already better. But how do we pass arguments to func ? Well for that we will use what’s called *args and **kwargs. If you are not familiar with them, go check out my story on the topic.

Here is the code using *args and **kwargs:

def my_decorator( func ):
    def decorated_func(*args, **kwargs):
        ...
        result = func(*args, **kwargs)
        ...
        return result
    return decorated_func

And now we have a functioning decorator. But for now, it doesn’t add any functionality, it’s time to add our timer code.

To implement our timer, we will use the built-in time module:

import time

And here is the implementation of the decorator:

def timer( func ):
    def decorated_func(*args, **kwargs):
        time_1 = time.time()
        result = func(*args, **kwargs)
        print(f"Timer : {time.time() - time_1}")
        return result
    return decorated_func

Let’s now try our timer!

I wrote a very simple function to test it:

def my_simple_function(n = 1000000):
    result = 0
    for i in range(n):
        result += sqrt(i)
    return result

And add this a the top of your file:

from math import sqrt

And let’s call our decorated function now:

print( timer(my_simple_function)() )

Here is the output:

Timer : 0.18866491317749023
666666166.4588418

We can see that our timer is working very well. Let’s try to pass an argument to my_simple_function now:

print( timer(my_simple_function)(2_000_000) )

And here is the output:

Timer : 0.38884878158569336
1885617375.8495038

It works completely. But if we want to call multiple times our decorated function, we could save it into a variable to only call once our decorator.

my_simple_function_with_timer = timer(my_simple_function)

And we can now call our function multiple times:

my_simple_function_with_timer(1_000)
my_simple_function_with_timer(10_000)
my_simple_function_with_timer(100_000)
my_simple_function_with_timer(1_000_000)

Output:

Timer : 0.00019359588623046875
Timer : 0.0024785995483398438
Timer : 0.026081323623657227
Timer : 0.2023618221282959

The syntactical sugar with @

OK, we can now create our own decorators.

For now, the way we decorate functions is not very understandable. We first need to define a function, then we need to call the decorator with our function as an argument, store the return function, and then we can use it.

Luckily for us, Python is full of syntactical sugar, and there is one for decorators. This syntax is used to decorate a function when we define them. Let me show you how it works. Here we have our function definition:

def my_simple_function(n = 1000000):
    result = 0
    for i in range(n):
        result += sqrt(i)
    return result

And all we have to do is to add this before function definition:

@timer

It looks like this:

@timer
def my_simple_function(n = 1000000):
    result = 0
    for i in range(n):
        result += sqrt(i)
    return result

And now if we call our function:

my_simple_function( 1_000_000 )

Here is the output:

Timer : 0.19669675827026367

Examples of well-known decorators

You have probably already seen this syntax in some code.

The most used decorators in Python are probably @staticmethodand @classmethod. They are built-in decorators used with Object-Oriented Programming which are used to define static methods and class methods.

Quickly, static methods and class methods are a bit like classic methods. The main difference is that static methods, as well as class methods, are not bound to an instance of an object. You can call a static or class method without even creating an instance of the class. Class methods take as the first parameter the class, which allows you to create an instance of the class inside of the method.

I won’t explain more here but feel free to inquire about OOP in Python.

The second case where you probably saw decorators is when coding a web app with a framework like Flask or FastAPI.

Here is a very simple example of a decorated function that you could find in Flask code.

@app.route("/login")
def login_page():
    return render_template('login.html')

Here you can see the decorator is app.route and we pass an argument "/login" (I will explain in the next part how to handle arguments).

With FastAPI, you could find a code like that:

@app.get("/users-data")
def get_users_data():
    return get_users_json()

It’s very similar to the previous code, the decorator is app.get and we pass an argument, "/users-data" .

These were just two examples of where decorators are used, but they are used in many other cases. This is why it’s an important concept in Python.

More advanced cases

OK, now you know the basics of decorators as well as a few examples of situations where it’s useful. In this part, I will try to go a bit further by explaining your more advanced use of decorators.

Pass arguments to decorators

First, as we saw with Flask and FastAPI, we can pass arguments to decorators. This may not be very useful for basic decorators but it’s very important in more advanced decorators like in web apps for example.

The first thing to do is to modify our decorator’s function to receive more than one argument.

Here, the syntax is a bit different from the basic syntax. You need to define a function, in a function, in a function. Yeah, that seems complex.

We need first to write a function that receives our argument(s). Then, inside of it, you need to define your decorator like you would have done without arguments, with the wrapper inside of it. It looks like that:

def decorator(argument):
    def decorator2(func):
        def wrapper(*args, **kwargs):
            do_someting_with(argument)
            result = func(*args, **kwargs)
            do_something_else_with(arugment)
            return result
        return wrapper
    return decorator2

Let’s write a more concrete decorator:

def print_decorator(message):
    def decorator(func):
        def wrapper(*args, **kwargs):
            print(message)
            return func(*args, **kwargs)
        return wrapper
    return decorator

Our decorator takes as the second argument as string ( message ) and print it before calling the function that’s decorated.

Now, if we use the syntax without @, it looks like this

result = print_decorator("Summing!")(get_sum_of)(2, 5)

We just pass as a second argument to the decorator our message.

With the @-syntax, it’s very intuitive, you just pass the argument to the decorator:

@print_message_before_function("Summing!")
def get_sum_of(a, b):
    return a + b

And that’s it! You can pass as many arguments as you want just like you would with a regular function.

Decorate a function multiple times

Sometimes, when working with decorators, you will need to decorate a function multiple times. For example in a situation like this:

@app.route("/home")
@login_required
def home_page():
    return render_template('user-home.html')

Here as you can see, here the function is decorated for a first time by login_required and then a second time by app.route . Decorate a function multiple times is very simple, you just put the decorators on top of each other.

Decorate a function multiple times is very simple, you just put the decorators on top of each other.

Yes, but what about the order of decoration?

Indeed, this is a very important thing to know. To test it, let’s re-use or print_decorator from the previous section.

What if we test something like that:

@print_decorator("1")
@print_decorator("2")
@print_decorator("3")
def my_function():
    print("Hello")

And we can then call it:

my_function()

And here is the output:

1
2
3
Hello

With this output, we can guess that our function looks like this:

print("1")
print("2")
print("3")
print("Hello")

And we wrote it like that:

...
print(message)
result = func(*args, **kwargs)
...

So we know that the first to be added to the function is the 3. This means that the first decorator to be executed is the closest to the function. This is an important thing to remember.

The first decorator to be executed is the closest to the function definition.

Solve naming problem

A problem you may run into when working with complex decorators is a naming problem. Indeed, sometimes in a program, you’ll need to use the function’s name ( func.__name__ ), or a module may need to use it. In that case, you have to be very careful with the name of your decorated function. Let me show you the problem if we use again the previous example of my_function, we can print the function’s name if we don’t decorate it:

print(my_function.__name__)

# OUTPUT :
# my_function

But if we decorate it:

print(my_function.__name__)

# OUTPUT :
# wrapper

We can see that the function’s name is actually the name of the function we defined in our decorator body.

What’s the problem so?

Well, it becomes a problem when you have multiple decorated functions:

@print_decorator("1")
def my_function():
    print("Hello")
    
@print_decorator("2")
def my_other_function():
    print("Bye")
    
print(my_function.__name__)
print(my_other_function.__name__)

Here is the output:

wrapper
wrapper

As you can see, the two functions have the same name, and that becomes a problem. Indeed, for example when the Flask framework store the routes of the web application, function’s names are used, and that’s why it’s a problem that two functions have the same name.

Luckily, the problem can be solved quite easily. We just need to change the function’s name to match its original one.

The __name__ is not only gettable but it’s settable too, so we can modify it very easily.

Writing the following is totally valid:

my_function.__name__ = "Any name that you want"

So we need to get the original name and set the wrapper’s name to this original name.

wrapper.__name__ = func.__name__

Here is the full code:

def print_decorator(message):
    def decorator(func):
        def wrapper(*args, **kwargs):
            print(message)
            return func(*args, **kwargs)
        wrapper.__name__ = func.__name__ # <--
        return wrapper
    return decorator

And now if we run again our code:

@print_decorator("1")
def my_function():
    print("Hello")
    
@print_decorator("2")
def my_other_function():
    print("Bye")
    
print(my_function.__name__)
print(my_other_function.__name__)

Here is the output:

my_function
my_other_function

Great! We no longer have any problem with our function name. So when you write a decorator, don’t forget to change the wrapper’s name to the function’s name!

Don’t forget to change the wrapper’s name to the function’s name!

Thanks for reading!

Follow me not to miss the next stories of this series!

See you in the next story! 👋

And as always, may the code be with you!

More content at plainenglish.io