🖼️🐍 Python Decorators Tutorial

Python Decorators Tutorial: Everything You Need to Know

Python decorators are one of the most powerful features in the language. They allow you to modify or extend the behavior of functions and methods without modifying their source code. In this Python decorators tutorial, we’ll explore how decorators work, how to use them effectively, and how they can enhance your code with minimal effort.

📌 What Are Python Decorators?

Decorators in Python are a design pattern that lets you add new functionality to an existing object or function. The beauty of decorators lies in their ability to modify the behavior of functions or methods dynamically, keeping your code clean, reusable, and flexible.

Decorators are usually applied to functions or methods using the @ syntax. They wrap functions, adding extra functionality before or after the decorated function is executed.

📌 Functions as First-Class Objects

In Python, functions are first-class citizens, meaning they can be passed around, returned from other functions, and assigned to variables. This makes Python highly flexible, and decorators are a great example of this flexibility.

🧩 Example: Assigning Functions to Variables

def plus_one(number):
    return number + 1

add_one = plus_one
add_one(5)  # Output: 6

💡 Here, add_one is assigned the function plus_one, demonstrating that functions can be stored in variables and called dynamically.

📌 Inner Functions and Closures

Closures are a fundamental concept for decorators. A closure is a nested function that remembers the environment in which it was created, even after the outer function has finished execution. This is how decorators are able to remember the function they decorate.

🧩 Example of a Closure:

def outer_function(message):
    def inner_function():
        print(f"Message from closure: {message}")
    return inner_function

closure_function = outer_function("Hello, closures!")
closure_function()  # Output: Message from closure: Hello, closures!

💡 The inner_function accesses the variable message from its enclosing scope, demonstrating a closure.

def outer():
    def inner():
        print("Hello from inner!")
    return inner

outer()()  # First call returns inner, second call executes it

def first():
    def second():
        def third():
            print("Deep inside!")
        return third
    return second

first()()()  # Output: Deep inside!

📌 Creating Your First Python Decorator

A decorator in Python is a function that takes another function as an argument and modifies its behavior. Here’s how you can create a simple decorator that converts a string to uppercase:

🧩 Simple Decorator Example:

def uppercase_decorator(function):
    def wrapper():
        result = function()
        return result.upper()
    return wrapper

@uppercase_decorator
def say_hi():
    return 'hello there'

print(say_hi())  # Output: HELLO THERE

💡 In this example, uppercase_decorator is applied to the say_hi function, which modifies the returned string to uppercase.

text = "hello"
print(text.upper())  # Output: HELLO

📌 Stacking Multiple Decorators

Python allows you to stack multiple decorators on a single function. The order of decorators is important, as they are applied from bottom to top.

🧩 Example of Stacking Decorators:

import functools

def uppercase_decorator(function):
    def wrapper():
        result = function()
        return result.upper()
    return wrapper

def split_string(function):
    @functools.wraps(function)
    def wrapper():
        result = function()
        return result.split()
    return wrapper

@split_string
@uppercase_decorator
def say_hi():
    return 'hello there'

print(say_hi())  # Output: ['HELLO', 'THERE']

💡 Here, the string is first converted to uppercase, then split into a list. The decorators are stacked from bottom to top.

@functools.wraps(function)

text = "hello there"
print(text.split())  # Output: ['hello', 'there']

@split_string
@uppercase_decorator
def say_hi():
    return 'hello there'

def decorator(func):
    def wrapper():
        return func()
    return wrapper

@decorator
def say_hi():
    """Says hi"""
    return "hi"

print(say_hi.__name__)  # Output: wrapper
print(say_hi.__doc__)   # Output: None

import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper():
        return func()
    return wrapper

@decorator
def say_hi():
    """Says hi"""
    return "hi"

print(say_hi.__name__)  # Output: say_hi
print(say_hi.__doc__)   # Output: Says hi

def greet():
    """This function says hello."""
    return "Hello!"

print(greet.__name__)   # Output: greet
print(greet.__doc__)    # Output: This function says hello.

📌 Accepting Arguments in Decorators

Sometimes, you may want to pass arguments into your decorators. To achieve this, you can define a decorator that accepts arguments by creating a decorator factory.

🧩 Example of a Decorator with Arguments:

def decorator_with_arguments(function):
    def wrapper_accepting_arguments(arg1, arg2):
        print(f"My arguments are: {arg1}, {arg2}")
        return function(arg1, arg2)
    return wrapper_accepting_arguments

@decorator_with_arguments
def cities(city_one, city_two):
    print(f"Cities I love are {city_one} and {city_two}")

cities("Nairobi", "Accra")

Output:

My arguments are: Nairobi, Accra
Cities I love are Nairobi and Accra

💡 This allows the decorator to work with arguments dynamically passed to the decorated function.

📌 **General-Purpose Decorators with *args and kwargs

To create a general-purpose decorator, you can use *args and **kwargs to accept any number of arguments and keyword arguments, making your decorator flexible and reusable.

🧩 Example of a General-Purpose Decorator:

def general_decorator(function):
    def wrapper(*args, **kwargs):
        print(f"Positional arguments: {args}")
        print(f"Keyword arguments: {kwargs}")
        return function(*args, **kwargs)
    return wrapper

@general_decorator
def greet(name, age):
    return f"Hello {name}, you are {age} years old."

print(greet("John", age=30))

💡 Output:

Positional arguments: ('John',)
Keyword arguments: {'age': 30}
Hello John, you are 30 years old.

💡 This decorator accepts any number of arguments and keywords, making it highly reusable.

📌 Debugging Decorators

One challenge with decorators is that they can obscure the original function’s metadata (like its name or docstring). To solve this, Python provides functools.wraps() to preserve the original function’s metadata when decorating it.

🧩 Example of Debugging with functools.wraps():

import functools

def uppercase_decorator(func):
    @functools.wraps(func)
    def wrapper():
        return func().upper()
    return wrapper

@uppercase_decorator
def greet():
    "This will say hi"
    return 'hello there'

print(greet())  # Output: HELLO THERE
print(greet.__name__)  # Output: greet
print(greet.__doc__)  # Output: This will say hi

💡This ensures the decorated function retains its original metadata.

📌 Class-Based Decorators

Class-based decorators offer more flexibility and maintainability, especially for more complex use cases. In a class-based decorator, you define a class with a  __call__  method, which allows the class to behave like a function.

🧩 Example of a Class-Based Decorator:

class UppercaseDecorator:
    def __init__(self, function):
        self.function = function

    def __call__(self, *args, **kwargs):
        result = self.function(*args, **kwargs)
        return result.upper()

@UppercaseDecorator
def greet():
    return "hello there"

print(greet())  # Output: HELLO THERE

💡 Class-based decorators can also maintain state, making them more powerful than function-based decorators in some scenarios.

📌 Real-World Decorator Use Case: Caching

@lru_cache is a decorator from the functools module that allows Python to cache (remember) the results of function calls. It improves performance by storing the output of expensive or frequently repeated function calls. This is especially useful for functions with repetitive calls, like in the Fibonacci sequence calculation.

🧩 Example: Caching with lru_cache:

from functools import lru_cache

@lru_cache(maxsize=128)
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(50))  # Subsequent calls with the same argument are faster #output: 12586269025

💡 This significantly improves performance by caching results of repeated function calls.

📌 Python Decorators Tutorial Summary

Python decorators are a powerful feature that allows you to extend the behavior of functions or methods without changing their core logic. They provide a way to write clean, reusable, and maintainable code. Decorators have a wide range of applications, such as logging, input validation, authorization, performance measurement, and more.

By mastering Python decorators, you can write more elegant and efficient Python code while following the DRY (Don’t Repeat Yourself) principle.

Source: Datacamp