Python Decorator: Enhance Your Code With Wrapping Wizardry Read it later

Python decorator is a powerful feature that can elevate your code to new heights. They allow you to modify the behavior of functions or classes without directly altering their source code. In this blog, we’ll dive into the world of decorators, covering their purpose, syntax, and practical use cases. By the end, you’ll have a strong grasp of decorators and how they can supercharge your Python code. Let’s embark on this enlightening journey together!

What is a Python Decorator?

In Python, a decorator is a design pattern that encloses a function within another function to improve its functionality without modifying the source code of the original function.

Why Use a Decorator?

Here are some reasons why you should use decorators in Python:

1. Simplified Higher-Order Functions: Decorators provide syntactic sugar for applying additional functionality to functions, making it easier to use higher-order functions and promote functional programming.
2. Aspect-Oriented Programming (AOP): Decorators enable AOP by separating cross-cutting concerns from core logic, allowing you to encapsulate and apply common functionalities selectively.
3. Domain-Specific Language (DSL) Creation: Decorators can help create DSL-like interfaces tailored to specific problem domains, enhancing code readability and clarity.
4. Context Managers and Resource Handling: Decorators simplify resource management by transforming functions into context managers, ensuring proper allocation and cleanup.
5. Dynamic Configuration and Feature Flagging: Decorators facilitate dynamic configuration and feature toggling, enabling runtime control over functionalities without modifying the original code.
6. Method Chaining and Fluent Interfaces: Decorators can create fluent interfaces and support method chaining, resulting in more expressive and concise code.

When to use Python Decorator?

We should try to use Python decorator where the emphasis is on:

1. Modifying Functionality: Use decorators when you want to modify the behavior of a function without changing its source code. Add functionality like logging or input validation, or modify return values and arguments.
2. Code Reusability: Decorators promote code reusability by separating common functionality from the core logic. Apply decorators to multiple functions or classes to avoid code duplication and maintain consistency.
3. Cross-Cutting Concerns: Decorators are great for handling tasks that are needed in multiple parts of your code, such as logging, caching, or authentication.
4. Performance Optimization: If you have computationally expensive operations or recursive functions, decorators can improve performance by implementing techniques like memoization.
5. Dynamic Behavior: Decorators allow you to dynamically modify the behavior of functions or classes at runtime. Use them to extend or customize the functionality of libraries, frameworks, or APIs.
6. Code Monitoring: Decorators can add metrics, monitoring, or error-handling capabilities to your code, making it more robust and maintainable.

Real-World Applications of Python Decorators

Here are some real-world applications where using decorators can be useful:

1. Authentication and Authorization: Decorators simplify protecting sensitive routes or functions in applications with user authentication and authorization systems. You can create an authentication decorator to ensure that only authorized users can access certain parts of your code.
2. Memoization and Performance Optimization: Decorators are valuable for optimizing computationally expensive operations or functions that require significant processing time. By creating a memoization decorator, you can cache function results, improving performance by avoiding redundant computations.
3. Input Validation and Preprocessing: Decorators provide reusable solutions for validating inputs to functions. Applying validation decorators ensures that your functions receive valid inputs, reducing the risk of errors or unexpected behavior.
4. API Rate Limiting and Throttling: When developing APIs, decorators simplify the implementation of rate limiting and throttling mechanisms. By applying a decorator to your API endpoints, you can restrict the number of requests per second, preventing abuse or overuse of your services.

Python Decorator Syntax

Now that we have a fundamental understanding of Python decorators, let’s delve into the process of creating your own decorators using the appropriate syntax.

To define a decorator, we use the “@” symbol followed by the name of the decorator function. This special syntax is known as “pie” syntax. It allows us to apply the decorator to a function or class effortlessly.

For example, let’s say we have a function called function() that we want to decorate. Here’s how we do it:

@decorator
def function():
    # Function body

In the above code, the @decorator line before the function definition is where the magic happens. It tells Python that we want to apply the decorator to the function below it.

I’ve seen this before, it’s a classic!

After seeing the decorator syntax, you might be like “I’ve seen this before, it’s a classic!” Indeed, decorators are a classic feature of Python that has proven to be invaluable in many real-world scenarios.

Let’s take a look at some Python libraries where decorators are commonly used.

Flask

Flask, a popular micro web framework, utilizes decorators extensively. One common decorator in Flask is @app.route, which is used to define the routes or endpoints of a web application.

Here’s an example:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def index():
    return 'Hello, Flask!'

In this example, the @app.route('/') decorator specifies that the index() function should be called when the root URL (/) is accessed.

Django

Django, another widely used web framework, also employs decorators in various ways. One example is the @login_required decorator, which ensures that only authenticated users can access certain views. Here’s an example:

from django.contrib.auth.decorators import login_required
from django.shortcuts import render

@login_required
def restricted_area(request):
    return render(request, 'restricted.html')

In this case, the @login_required decorator protects the restricted_area() view by redirecting any unauthenticated users to the login page.

Celery

Celery is a distributed task queue library used for background job processing. It utilizes the @task decorator to mark functions as tasks that can be executed asynchronously.

Example:

from celery import Celery

app = Celery('myapp', broker='pyamqp://guest@localhost//')

@app.task
def add(x, y):
    return x + y

The @app.task decorator designates the add() function as a Celery task that can be executed independently from the main application.

Pytest

The pytest testing framework allows you to create test functions and use decorators to mark them as test cases. One such decorator is @pytest.mark.parametrize, which enables the parameterization of tests.

Example:

import pytest

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

@pytest.mark.parametrize('a, b, expected', [
    (1, 2, 3),
    (4, 5, 9),
    (10, 0, 10)
])
def test_add(a, b, expected):
    assert add(a, b) == expected

In this case, the @pytest.mark.parametrize decorator allows you to define multiple test cases with different input values for the add() function.

Now that we have grasped the essence of decorator syntax and explored its applications in various Python libraries, let’s dive deeper into the inner workings of decorators.

What is a First-Class Object in Python?

To truly grasp the concept of decorators in Python, it’s crucial to first understand the concept of first-class objects.

In Python, a first-class object refers to an object that can be assigned to variables, passed as arguments to functions, and returned as the result of a function.

Functions as First-Class Objects

Python treats functions as first-class objects, which means they can be assigned to variables, passed as arguments to other functions, and even returned as values from other functions. This unique characteristic forms the foundation for the power and flexibility of decorators.

Let’s take a look at an example:

def greet():
    print("Hello, World!")

# Assigning the function to a variable
say_hello = greet

# Calling the function through the variable
say_hello()

In this example, the greet() function is assigned to the variable say_hello. Now, we can then call the function using the variable name, say_hello(), and it will execute the code inside the greet() function, resulting in the output Hello, World!.

Properties of First-Class Functions

First-class functions in Python possess key properties that make them incredibly versatile:

1. Functions are treated as objects, allowing them to be stored in variables.
2. Functions can be assigned to variables for flexible use.
3. Functions can be passed as arguments to other functions.
4. Functions can be returned as values from other functions.
5. Functions can be stored in data structures like lists or dictionaries.

How Decorator Works in Python?

The ability to treat a function as a first-class object plays a vital role in enabling decorators to modify the behavior of other functions, inject additional functionality, and alter the execution flow, all without modifying their source code directly.

Example:

def decorator_function(func):
    def wrapper():
        print("Executing some code before the original function.")
        func()
        print("Executing some code after the original function.")
    return wrapper

@decorator_function
def greet():
    print("Hello, World!")

greet()

In this example, we define a decorator called decorator_function. The wrapper function is responsible for printing a message before and after the execution of the decorated function, greet. We then apply the decorator_function to the greet function using the @ syntax.

The above decorator syntax can also be written as:

def decorator_function(func):
    def wrapper():
        print("Executing some code before the original function.")
        func()
        print("Executing some code after the original function.")
    return wrapper

def greet():
    print("Hello, World!")

decorated_greet = decorator_function(greet)
decorated_greet()

In this example, we have a decorator function named decorator_function that takes a function (func) as an argument. The decorator_function returns inner function called wrapper, which wraps the original function greet(). The wrapper() performs some additional actions before and after calling the original function.

By calling decorator_function(greet), we obtain the decorated version of the greet() function, stored in the variable decorated_greet. When we execute decorated_greet(), it triggers the execution of the wrapper() function, resulting in the desired behavior of the decorator.

Output:

Executing some code before the original function.
Hello, World!
Executing some code after the original function.

Decorator Chaining in Python

In Python, it is possible to apply multiple decorators as a chain to a single function, allowing you to stack the functionality and modify the behavior in a layered manner.

This can be especially useful when you need to add multiple enhancements to a function without cluttering its original code. Let’s explore how to apply multiple decorators to a function and witness their combined effect.

To demonstrate this concept, let’s consider a simple example. We have a function called greet() that prints a personalized greeting message. We want to enhance this function by adding two decorators: one for logging the function call and another for timing its execution.

Here’s the code for the greet() function:

import time

def timing_decorator(func):
    def wrapper():
        start_time = time.time()
        result = func()
        end_time = time.time()
        execution_time = end_time - start_time
        print(f"Function {func.__name__} executed in {execution_time:.4f} seconds.")
        return result
    return wrapper

def log_decorator(func):
    def wrapper():
        print(f"Calling function: {func.__name__}")
        result = func()
        print(f"Function {func.__name__} executed.")
        return result
    return wrapper

@log_decorator
@timing_decorator
def greet():
    print(f"Hello, Hack The Developer!")

greet()

This is equivalent to:

func = log_decorator(timing_decorator(greet)))
func()

Output:

Calling function: wrapper
Hello, Hack The Developer!
Function greet executed in 0.0012 seconds.
Function wrapper executed.

Python Decorator Order of Execution

When it comes to the order in which decorators are executed, there are two important aspects to consider:

1. Evaluation during function definition and,
2. Execution during function calls.

Let’s dive into how the decorator’s order of execution works in a simple and understandable manner.

Evaluation During Function Definition

When the Python interpreter evaluates the decorated method definition, the decorators are evaluated from bottom to top.

Following a bottom-to-top order during function definition ensures that each decorator modifies the behavior of the function based on the changes made by the decorator below it. This sequence allows decorators to stack up and add functionality incrementally.

Execution During Function Calls

When the interpreter calls the decorated method, the decorators are executed from top to bottom (Reverse of a function definition).

To illustrate this, let’s consider an example with three decorators applied to a function:

def decorator1(func):
    print("Decorator 1")
    def wrapper():
        print("Decorator 1 wrapper before function...")
        func()
        print("Decorator 1 wrapper after function...")
    return wrapper

def decorator2(func):
    print("Decorator 2")
    def wrapper():
        print("Decorator 2 wrapper before function...")
        func()
        print("Decorator 2 wrapper after function...")
    return wrapper

def decorator3(func):
    print("Decorator 3")
    def wrapper():
        print("Decorator 3 wrapper before function...")
        func()
        print("Decorator 3 wrapper after function...")
    return wrapper

@decorator1
@decorator2
@decorator3
def my_function():
    print("Hello, world!")

my_function()

This is equivalent to:

func = decorator1(decorator2(decorator3(my_function)))
func()

Here’s the order of execution for this example:

1. During Function Definition (Bottup to Top)
   • Decorator 3 is evaluated and applied to the function.
   • Decorator 2 is evaluated and applied to the function with the result of Decorator 3.
   • Decorator 1 is evaluated and applied to the function with the result of Decorator 2.
2. During Function Calls (Top to Bottom): When my_function() is called, the inner functions of the decorator are executed in the opposite order.
   • Decorator 1’s wrapper is called first, printing Decorator 1 wrapper before function....
   • Decorator 2’s wrapper is called next, printing Decorator 2 wrapper before function....
   • Decorator 3’s wrapper is called last, printing Decorator 3 wrapper before function....
   • The actual function code print("Hello, world!") is executed.
   • Decorator 3’s wrapper is called again, printing Decorator 3 wrapper after function....
   • Decorator 2’s wrapper is called again, printing Decorator 2 wrapper after function....
   • Decorator 1’s wrapper is called again, printing Decorator 1 wrapper after function....

In the example provided, the output would be:

Decorator 3
Decorator 2
Decorator 1
Decorator 1 wrapper before function...
Decorator 2 wrapper before function...
Decorator 3 wrapper before function...
Hello, world!
Decorator 3 wrapper after function...
Decorator 2 wrapper after function...
Decorator 1 wrapper after function...

📝 Note: The order in which you apply the Python decorators matters, so choose the order wisely to achieve the desired functionality.

Return Values From Python Decorator

When working with Python decorators, it’s crucial to understand how to correctly return values from the inner wrapper function. Let’s learn it from a mistake that we generally make while working with decorators in Python.

Consider the following example:

def double(func):
    def wrapper(*args, **kwargs):
        2 * func(*args, **kwargs)
    return wrapper

@double
def add(a, b):
    return a + b

print(add(5, 2))  # None

In this case, when we execute the add(5, 2) function call, we obtain None instead of the expected result. Why does this happen?

The reason is that the inner function, wrapper, does not have a return statement. As a result, even if the func(*args, **kwargs) call inside the wrapper function returns a value, it is not being explicitly returned. Consequently, the value returned by the original function, add, is lost, leading to None being returned instead.

To ensure that the correct value is returned, we need to modify the decorator function to include a return statement in the inner function.

Let’s see the corrected code:

def double(func):
    def wrapper(*args, **kwargs):
        return 2 * func(*args, **kwargs)
    return wrapper

@double
def add(a, b):
    return a + b

print(add(5, 2))  # 14

In this updated version, the wrapper function now includes the necessary return statement. It returns the result of 2 * func(*args, **kwargs), ensuring that the value returned by the original function, add, is correctly captured and passed on.

Now, when we call add(5, 2), we obtain the expected result of 14. By adding the return statement within the inner function of the decorator, we preserve and propagate the return value of the decorated function.

Python Decorator Add Argument to Function

To pass arguments to the decorated function in Python, we utilize *args and **kwargs. Here’s a simplified breakdown of the process:

1. Define the decorator function.
2. Implement a wrapper function within the decorator that accepts *args and **kwargs.
3. Invoke the original function inside the wrapper function using *args and **kwargs syntax.

Syntax:

def custom_decorator(func):
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result
    return wrapper

With *args, we can pass an unlimited number of positional arguments, such as integers or strings. **kwargs allows us to pass an unlimited number of keyword arguments, like key=value. This flexibility empowers us to create versatile decorators that can adapt to different scenarios and provide dynamic inputs to the decorated function.

Example:

def wish(func):
    def wrapper(*args, **kwargs):
        print("Good Morning!")
        func(*args, **kwargs)
    
    return wrapper

@wish
def greet(name):
    print(f"Hello, {name}")

greet("Hack The Developer")

This is equivalent to:

func = wish(greet)
func("Hack The Developer")

Output:

Good Morning!
Hello, Hack The Developer

Passing Argument to Decorator in Python

Now, let’s dive into the process of passing arguments to decorators in Python. It may seem a bit confusing at first, but fear not – we’re here to guide you through the steps. So, let’s break it down into a simple and concise process:

1. Define a Decorator Factory

Create a function that generates the actual decorator based on the provided arguments.

def repeat(n):
    def decorator_func(func):
        def wrapper(*args, **kwargs):
            for _ in range(n):
                func(*args, **kwargs)
        return wrapper
    return decorator_func

2. Set Up the Decorator

Apply the decorator using the “@” symbol followed by the name of the decorator factory.

@repeat(3)
def greet(name):
    print(f"Hello, {name}!")

This is equivalent to:

func = repeat(3)(greet)
func("HTD")

Output:

Hello, HTD!
Hello, HTD!
Hello, HTD!

Decorating a Python Class

A Python decorator can also be applied to classes, allowing you to modify the behavior and attributes of the entire class. This provides powerful enhancements to its functionality. To decorate a class, you define a decorator function that takes the class as an argument and returns a modified version of the class.

Here’s an example of decorating a class with a timing decorator:

import time

def timing_decorator(cls):
    class DecoratedClass(cls):
        def __getattribute__(self, name):
            start_time = time.time()
            result = super().__getattribute__(name)
            end_time = time.time()
            execution_time = end_time - start_time
            print(f"Method {name} executed in {execution_time} seconds.")
            return result
    return DecoratedClass

@timing_decorator
class MyClass:
    def method1(self):
        time.sleep(1)
        print("Method 1 executed.")

    def method2(self):
        time.sleep(2)
        print("Method 2 executed.")

my_object = MyClass()
my_object.method1()
my_object.method2()

This is equivalent to:

obj = timing_decorator(MyClass)()
obj.method1()
obj.method2()

In this example, the timing_decorator takes the class as an argument. It creates a new class, DecoratedClass, which inherits from the original class.

The __getattribute__ method is overridden to measure the execution time of each method call. By applying the timing_decorator to the MyClass definition, the class behavior is modified.

When the class methods are called, the decorator measures the execution time and provides the timing information.

Output:

Method method1 executed in 0.001 seconds.
Method 1 executed.
Method method2 executed in 0.004 seconds.
Method 2 executed.

Class as Decorator

Another fascinating aspect of Python decorators is their ability to use classes as decorators. Yes, you read it right! You can employ a class as a decorator to enhance the behavior of functions or other classes.

To use a class as a decorator, we need to define the class with two special methods: __init__() and __call__().

The __init__() method is executed when the decorator class is instantiated, while the __call__() method is invoked when the decorated function or class is called. This separation of concerns allows us to perform setup tasks in __init__() and modify behavior during the function or class execution in __call__().

Let’s illustrate this concept with an example:

class DecoratorClass:
    def __init__(self, func):
        self.func = func

    def __call__(self, *args, **kwargs):
        print("Before function execution")
        result = self.func(*args, **kwargs)
        print("After function execution")
        return result

@DecoratorClass
def decorated_function():
    print("Inside the decorated function")

decorated_function()

This is equivalent to:

func = DecoratorClass(decorated_function)
func()

In the example above, we define the DecoratorClass with __init__() and __call__() methods. The __init__() method takes the decorated function as an argument and stores it in the self.func attribute for later use. The __call__() method is executed when the decorated_function() is called. It performs the necessary actions before and after executing the original function.

Output:

Before function execution
Inside the decorated function
After function execution

Accessing Original Attribute of a Function and Class

When using decorators in Python, one common issue that arises is the hiding of the original attributes of the function or class being decorated.

Let’s consider an example to understand this problem:

def my_decorator_func(func):
    def wrapper_func(*args, **kwargs):
        func(*args, **kwargs)
    return wrapper_func

@my_decorator_func
def my_func(my_args):
    '''Example docstring for function'''
    pass

print(my_func.__name__)
print(my_func.__doc__)

Output:

wrapper_func
None

As you can see, the output of my_func.__name__ is wrapper_func, and my_func.__doc__ returns None. This behavior can be unexpected and inconvenient when you’re trying to access the original attributes of the decorated function.

To overcome this issue, Python provides the functools.wraps decorator. By using wraps, we can update the decorator function with the attributes of the decorated function.

Let’s see how we can apply it to both functions and classes:

Using functools.wraps with Functions

from functools import wraps

def my_decorator_func(func):
    @wraps(func)
    def wrapper_func(*args, **kwargs):
        func(*args, **kwargs)
    return wrapper_func

@my_decorator_func
def my_func(my_args):
    '''Example docstring for function'''
    pass

print(my_func.__name__)
print(my_func.__doc__)

Output:

my_func
Example docstring for function

By adding @wraps(func) above the inner wrapper function, we ensure that the attributes of func are preserved. Now, my_func.__name__ correctly returns my_func, and my_func.__doc__ displays the original docstring.

Using functools.wraps with Classes:

from functools import wraps

def my_decorator_class(cls):
    @wraps(cls)
    class WrapperClass:
        def __init__(self, *args, **kwargs):
            self.wrapped = cls(*args, **kwargs)

        def __getattr__(self, name):
            return getattr(self.wrapped, name)

    return WrapperClass

@my_decorator_class
class MyClass:
    '''Example class with a docstring'''

    def my_method(self):
        pass

obj = MyClass()
print(obj.__class__.__name__)
print(obj.__doc__)

Output:

MyClass
Example class with a docstring

Here, we apply @wraps(cls) to the inner WrapperClass to preserve the original attributes of the class. The resulting object obj retains the class name as MyClass and the docstring as Example class with a docstring.

Wrapping Up

In conclusion, Python decorators are a powerful tool for enhancing the behavior and flexibility of your code. By wrapping functions or classes with additional functionality, decorators allow you to modify their behavior without directly changing their source code.

Throughout this blog, we’ve covered the basics of decorators, including syntax, creation, and application. We’ve also explored common use cases and touched on advanced concepts.

By leveraging decorators effectively, you can elevate your code’s functionality and maintainability. They provide a flexible and elegant solution for adding layers of behavior to your Python projects.

Start experimenting with decorators in your own code and unlock their true potential. Happy coding!

Frequently Asked Questions (FAQs)

Reference

• Decorators in Python – Python Documentation
• https://peps.python.org/pep-0318/