Important Python Decorator

In this tutorial, we will learn about some amazing Python decorators that every Python developer should know. These decorators will help to take the code to the next level and do more things in less code.

As we know, Python decorators are a powerful tool that helps to write scalable and clean code. To understand this tutorial, one should be familiar with the decorator. If you are new to decorator then below is a brief introduction to the decorator.

In Python, a decorator is a special type of function that can be used to modify the behavior of another function or class. A decorator takes a function or class as input, performs some modification on it, and returns the modified function or class.

Decorators are denoted by the @symbol followed by the decorator function's name and placed immediately before the function or class to be decorated. When the decorated function or class is called, the decorator function is executed first, and its result is used as the new function or class.

Example -

def log(func):
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__} with arguments {args}, {kwargs}")
        result = func(*args, **kwargs)
        print(f"Returned {result}")
        return result
    return wrapper

@log
def add(x, y):
    return x + y

result = add(3, 4)
print(result)   

Output:

Now, we will see the list of important Python decorator.

1. @logger

The logger is a function that takes a function as an argument and returns a function as output. The output is modified as per the decorator logic. In this section, we will create the logger decorator. Since we don't know the function input, we will pass *arg and **kwarg. The *arg and **kwarg argument allows us to pass an arbitrary number of positional and keyword arguments. Let's see the following implementation of the logger decorator.

Example -

def logger(function):
    def wrapper(*args, **kwargs):
        print(f"----- {function.__name__}: Function start -----")
        output = function(*args, **kwargs)
        print(f"----- {function.__name__}: Function end -----")
        return output
    return wrapper

We can apply the above decorator on any function and modify its result.

decorator_function = logger(function_argument)

We can also apply the decorator using the @symbol. Let's see the following example.

@logger
def get_text(text):
    print(text)

get_text('The Decorator is called')

Output:

----- get_text: Function start -----
The Decorator is called
----- get_text: Function end -----

2. @lru_cache

It comes with the Python functools module, we can import it. It returns the values of a function, using a least-recently-used (LRU) algorithm. If the cache is full, it discards the least-used values. This decorator is quite useful in long-running tasks that don't change the output with the same input, such as requesting a static, removing a web page, or querying a database. Following is the example of the @lru_decorator.

Example -

import random
import time
from functools import lru_cache

@lru_cache(maxsize=None)
def heavy_processing(n):
    sleep_time = n + random.random()
    time.sleep(sleep_time)

# first time
heavy_processing(0)
# CPU times: user 363 �s, sys: 727 �s, total: 1.09 ms
# Wall time: 694 ms

# second time
heavy_processing(0)
# CPU times: user 4 �s, sys: 0 ns, total: 4 �s
# Wall time: 8.11 �s

# third time
heavy_processing(0)
# CPU times: user 5 �s, sys: 1 �s, total: 6 �s
# Wall time: 7.15 �s

Explanation -

To create a cache decorator from scratch, we would start by adding a dictionary as an attribute to the wrapper function. This dictionary would serve as a place to store previously computed values returned by the input function.

When the input function is called, the decorator would first check if the arguments passed to the function have already been computed and stored in the cache; the decorator would return the cached result. Otherwise, the decorator would compute the result and add it to the cache for future use.

3. @repeat

The repeat decorator is responsible for the multiple times in a row. It helps debug purposes, stress tests, or automate multiple tasks' repetition. Let's understand the following example -

Example -

from functools import wraps
def repeat(number_of_times):
    def decorate(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(number_of_times):
                func(*args, **kwargs)
        return wrapper
    return decorate

In the above code, we define a decorator called repeat that takes multiple arguments. We import the wraps decorator which is wrapped around the function being decorated. The wrapper function calls the decorated function a number of times equal to the definite number.

@repeat(10)
def get_value():
    print('Hi, There')

get_value()

Output:

Hi, There
Hi, There
Hi, There
Hi, There
Hi, There
Hi, There
Hi, There
Hi, There
Hi, There
Hi, There

4. @timeit

This decorator calculates the execution times of a function and prints the result. It can be used in debugging or monitoring. Let's understand the following example.

Example -

import time
from functools import wraps

def timeit(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        start_time = time.perf_counter()
        result = func(*args, **kwargs)
        end_time = time.perf_counter()
        print(f'{func.__name__} took {end_time - start_time:.6f} seconds to complete')
        return result
    return wrapper

@timeit
def process_data():
    time.sleep(1)

process_data()

Output:

process_data took 1.003516 seconds to complete

5. @retry

The @retry decorator in Python is a useful tool for automatically retrying a function when it fails due to certain exceptions. This decorator can be applied to any function and can be customized to retry the function with different parameters based on the type of exception that caused the failure.

Here is an example of how to use the @retry decorator in Python.

Example -

from retry import retry
@retry(tries=3, delay=2, backoff=2, jitter=(1, 3))
def my_function():
    # code that may raise an exception

Explanation -

In this example, the my_function() function will be retried up to 3 times with a delay of 2 seconds between each retry. The backoff parameter specifies that the delay between retries will double after each retry, and the jitter parameter specifies that the delay between retries will be randomly varied between 1 and 3 seconds to avoid retry storms.

By default, the @retry decorator will retry the function if any exception is raised. However, you can specify a list of exceptions to retry on by passing the retry_on_exception parameter.

@retry(tries=3, delay=2, backoff=2, jitter=(1, 3), retry_on_exception=[ValueError, TypeError])
def my_function():
    # code that may raise a ValueError or TypeError

In the above code, my_function will only be retried if a ValueError or TypeError is raised.

Note that the @retry decorator is not built-in to Python and needs to be installed separately. There are several libraries that provide the @retry decorator, such as retrying and tenacity.

7. @wraps

This decorator is used to preserve the original function's name docstring. Let's understand the following example.

Example -

from functools import wraps

def my_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print("Before the function is called.")
        result = func(*args, **kwargs)
        print("After the function is called.")
        return result
    return wrapper
@my_decorator
def add_numbers(x, y):
    """
    This function adds two numbers.
    """
    return x + y

Explanation -

In the above code, we are using the @wraps decorator to preserve the name and docstring of the original add_numbers() function. Without @wraps, the decorated function would have a different name and docstring, which could be confusing and make debugging more difficult.

Here's an example of how to use the add_numbers function.

Example -

result = add_numbers(1, 2)
print(result)  
print(add_numbers.__name__)  
print(add_numbers.__doc__)   

Output:

3
add_number
This function adds two numbers

7. @rate_limited

The @rate_limited decorator is used to limit the rate at which a function can be called, by sleeping an amount of time if the function is called too frequently.

Example -

import time
from functools import wraps

def rate_limited(max_per_second):
    """
    Decorator that limits the rate at which a function can be called.
    """
    min_interval = 1.0 / float(max_per_second)
    
    def decorate(func):
        last_time_called = [0.0]
        
        @wraps(func)
        def rate_limited_function(*args, **kwargs):
            elapsed = time.perf_counter() - last_time_called[0]
            left_to_wait = min_interval - elapsed
            
            if left_to_wait > 0:
                time.sleep(left_to_wait)
            
            last_time_called[0] = time.perf_counter()
            return func(*args, **kwargs)
        
        return rate_limited_function
    return decorate

Explanation -

In the above code, we are using the rate_limited decorator to limit the rate at which a function can be called. The max_per_second parameter specifies the maximum number of times per second the function can be called.

The decorate function is defined inside the rate_limited decorator and is used to wrap the original function with the rate-limiting logic. We use a list last_time_called to store the last time the function was called, and it allows us to update the previous call time inside the rate_limited_function even though the last_time_called is a mutable object.

The rate_limited_function wraps the original function and calculates the time elapsed since the last call to the function. If the elapsed time is less than the minimum interval, the function sleeps for the difference between the minimum interval and the elapsed time. The last call time is then updated, and the original function is called with the provided arguments.

@rate_limited(max_per_second=2)
def my_function():
    print("Hello, world!")

# Call the function 5 times, should only print "Hello, world!" twice
for i in range(5):
    my_function()

Output:

Hello, world!
Hello, world!
Hello, world!
Hello, world!
Hello, world

In the above code, the my_function() function is rate-limited to a maximum of 2 calls per second. When we call the function 5 times in a loop, it only prints "Hello, world!" twice because the rate-limiting decorator sleeps for the appropriate amount of time between calls.

8. @dataclass

The @dataclass decorator is used to decorate the classes. When we decorate a class with @dataclass decorator, the decorator automatically generates several special methods for the class, such as __init__(), __repr__(), __eq__(), and others, based on the class attributes. This saves the programmer efforts of defining these methods manually, which can be tedious and error-prone, especially for classes with many attributes. It also provides nifty methods off-the-shelf to represent objects nicely, convert them into JSON format, make them immutable, etc.

This decorator was introduced in Python 3.7 and is available in the standard library.

Let's understand the following example.

Example -

from dataclasses import dataclass

@dataclass
class Car:
    make: str
    model: str
    year: int
    price: float

car1 = Car("Honda", "Civic", 2022, 25000.0)
car2 = Car("Toyota", "Corolla", 2022, 24000.0)

print(car1)
print(car2)
print(car1 == car2)

Output:

Car(make='Honda', model='Civic', year=2022, price=25000.0)
Car(make='Toyota', model='Corolla', year=2022, price=24000.0)
False

Explanation -

In the above code, we define a Car class with four attributes: make, model, year, and price. The @dataclass decorator automatically generates several special methods for the class, including an __init__() method that takes the four attributes as arguments, a __repr__() method that returns a string representation of the object, and an __eq__() method that compares two objects based on their attributes.

We then create two instances of the Car class, car1 and car2, and print them to the console. Finally, we compare car1 and car2 using the == operator, which invokes the __eq__() method generated by the @dataclass decorator.

9. @singledispatch

The @singledispatch decorator is a function decorator in Python's functools module that defines a generic function that behaves differently based on its argument(s) type. It provides a simple way to implement polymorphic behavior in Python.

Below is an example of how to use the @singledispatch decorator.

Example - from functools import singledispatch

@singledispatch
def myfunc(arg):
    print("Unknown type argument")

@myfunc.register
def _(arg: int):
    print("This is an integer:", arg)

@myfunc.register
def _(arg: str):
    print("This is a string:", arg)

myfunc(42)
myfunc("hello")
myfunc(3.14)

Output:

This is an integer: 42
This is a string: hello
Unknown type argument

Explanation -

In the above code, we define a generic function called myfunc using the @singledispatch decorator. The function is initially defined to print a generic message when called with any argument type.

We then use the register() method to define specific implementations of myfunc for the int and str types. The _ identifier is used to indicate that the function doesn't use the parameter.

10. @register

The @register decorator can be useful in a situation where your Python script terminates unexpectedly, but we still want to perform some actions before it exits. Registering a function with the @register decorator ensures that the function is called before the script exits, even if an error occurs.

For example, we could use the @register decorator to register a cleanup function that saves our work or prints a message before the script terminates. It can be especially useful in long-running scripts or scripts that perform important tasks.

It @register decorator provides a simple and flexible way to perform actions before a script exits, regardless of the reason for termination.

Conclusion

Decorators are powerful tools for enhancing your code by adding new functionality such as caching, logging, rate limiting, and automatic retry. They can also be used to transform your classes into more versatile data containers.

By leveraging the power of decorators, you can make your code more modular, more efficient, and more flexible. Whether you're working on a large-scale project or a small personal script, decorators can help you take your code to the next level.

Next TopicPendulum Library in Python

← prev next →