Decorators

Theory

In Python, functions are just objects. You can treat a function exactly like a string, an integer, or a list.

A Higher Order Function (HOF) is a function that does at least one of the following:

•Takes another function as an input (argument).

•Returns a function as its output.

Analogy: If a normal function is a hammer (it does one job), a Higher Order Function is a Factory. The factory doesn't just build things; it can take in an old tool, upgrade it, and hand you back a "Power Hammer."

Code Snippets

Python

# Function as an object

def yell(text):

    return text.upper()

# Passing a function as an argument

def execute(func, value):

    return func(value)

print(execute(yell, "hello")) # Output: 'HELLO'

Question: If you have a function called greet(), what is the difference between these two lines of code?

1.x = greet

2.x = greet()

Answer: In the first line (x = greet), you are referencing the function. You are essentially giving the function a "nickname" (x). You haven't actually "run" the code yet.

•In the second line (x = greet()), you are executing (calling) the function. The variable x will store whatever the function returns (like a string or a number).

Common Mistake: 

• The "Eager Execution" Trap:

Theory:

A common mistake for beginners is accidentally calling a function when they only meant to pass it. This happens when you include parentheses () during the assignment or as an argument. This causes the function to run immediately, and you end up passing the result (like a string) instead of the tool (the function).

Code Snippet: 

Python

def get_admin_status():

    return "Access Denied"

def check_permission(func):

    # We expect 'func' to be a function we can call

    return f"Status check: {func()}"

# MISTAKE: Calling the function while passing it

# result = check_permission(get_admin_status()) 

# This passes "Access Denied" (a string) instead of the function itself!

Think About It: If a function returns None, and you accidentally "eagerly execute" it while passing it to an HOF, what error message will you likely see inside the HOF?
Answer: You will see a TypeError: 'NoneType' object is not callable. This happens because the HOF tries to "run" the result of your function (which is None) as if it were a function.

Edge Case Scenario:

• Assigning Metadata to Function Objects:

Theory: Since functions are objects, you can actually attach your own attributes to them without using a dictionary or a class. This is a "quick and dirty" way to store metadata directly on the tool itself.

Code Snippet: 

Python

def translate(text):

    return text.lower()

# Functions are objects, so we can add custom attributes!

translate.language = "English"

translate.version = "2.1"

print(f"Running {translate.language} translator v{translate.version}")

Think About It: Why might a developer use func.description = "..." instead of just writing a docstring """..."""?
Answer: Docstrings are primarily for documentation and help menus. Custom attributes allow the code to "read" and use that data programmatically during execution, such as a routing system that checks func.permission_level before running.

Theory

A Decorator is a Higher Order Function that "wraps" another function to add extra behavior. When you see the @decorator symbol above a function, you are telling Python: "Before you run this function, pass it through the decorator factory first."

The Metadata Problem: When you wrap a function, Python technically replaces your original function with the wrapper. This causes the original function to "forget" its name (__name__) and its help text (__doc__). @functools.wraps is a built-in decorator that "copies and pastes" the identity of the original function onto the wrapper so your code doesn't break.

Code Snippets

Python

from functools import wraps

def security_log(func):

    @wraps(func) #This saves the function's identity

    def wrapper(*args, **kwargs):

        print(f"[LOG]: Calling {func.__name__}...")

        return func(*args, **kwargs)

    return wrapper

@security_log

def open_vault():

    """Unlock the treasure."""

    print("Vault Opened!")

print(open_vault.__name__) # 'open_vault' (Correct!)

Think About It: What happens if you forget to return result inside the wrapper?
Answer: The original function will run, but the caller will receive None. This is a common bug where developers forget that the wrapper must "pass back" the output of the original function.

Common Mistake: 

• The "Vanishing" Return Value:

Theory: 

Beginners often forget that the wrapper is a middle-man. If the original function returns a value, the wrapper must capture and return it, otherwise the caller will always receive None.

Python
#MISTAKE

def bad_wrapper(func):

    def wrapper(*args, **kwargs):

        func(*args, **kwargs) # Runs the function, but DISCARDS the return!

    return wrapper

#FIX

def good_wrapper(func):

    def wrapper(*args, **kwargs):

        return func(*args, **kwargs) # Properly returns the result

    return wrapper

Think About It: What happens if you run x = my_decorated_function() using the bad_wrapper? What will x contain?.
Answer: The variable x will be None. Even if the original function performed a complex calculation, the "middle-man" (the wrapper) forgot to hand the result back to you.

Edge Case Scenario:

• Decorating Methods vs. Functions:

Theory: Class methods have a "hidden" first argument: self. Because decorators use the universal *args signature, self is automatically captured as the first item in the args tuple, meaning the same decorator works for both standalone functions and class methods.

Code Snippet: 

Python

from functools import wraps

def debug_args(func):

    @wraps(func)

    def wrapper(*args, **kwargs):

        print(f"DEBUG: args contents -> {args}")

        return func(*args, **kwargs)

    return wrapper

class Calculator:

    @debug_args

    def multiply(self, a, b):

        return a * b

calc = Calculator()

calc.multiply(5, 10) # args will be (<Calculator object>, 5, 10)

Think About It: If you manually defined def wrapper(a, b): instead of *args, would this decorator still work for the class method?.
Answer: No. It would crash with a TypeError because the class method actually receives three arguments (self, a, and b), but your wrapper was only designed to accept two.

Theory

Sometimes you want a "Configurable Decorator." For example, a decorator that limits how many times a user can try to log in. To do this, you need three levels of nested functions:

1.Level 1 (The Configurator): Takes the settings (e.g., max_tries=3).

2.Level 2 (The Decorator): Takes the actual function to be wrapped.

3.Level 3 (The Wrapper): The code that actually runs every time the function is called.

Code Snippets

Python

def print_message(msg):

    def decorator(func):

        @wraps(func)

        def wrapper(*args, **kwargs):

            print(f"Announcement: {msg}")

            return func(*args, **kwargs)

        return wrapper

    return decorator

@print_message("System Update Starting...")

def upgrade():

    print("Installing files...")

Question: If a decorator with arguments requires three levels of functions (the Configurator, the Decorator, and the Wrapper), why does a standard decorator only need two?
Answer: Because the "outermost" layer's only job is to capture the arguments (like times=3) and stay in memory via a Closure. Once those arguments are locked in, it returns the actual decorator, which then proceeds to wrap the function like normal.

Common Mistake: 

• The "Brittle" Signature:

Theory: Defining a wrapper as def wrapper(): creates a "Brittle Decorator" that only works on functions with zero arguments. You must always use *args and **kwargs so the decorator can handle any function inputs.

Python
#THE MISTAKE: Rigid Wrapper

def log_start(func):

    def wrapper(): # 0 arguments allowed!

        print("Starting...")

        return func()

    return wrapper

#THE FIX: Universal Wrapper

def log_start_fixed(func):

    def wrapper(*args, **kwargs): # Accepts ANY arguments

        print("Starting...")

        return func(*args, **kwargs)

    return wrapper

Think About It: Why is *args, **kwargs called the "Universal Signature" in Python development?.
Answer: Because it acts as a "catch-all". *args collects any number of positional inputs into a tuple, and **kwargs collects all named inputs into a dictionary, ensuring no data is lost.

Edge Case Scenario:

• Optional Decorator Arguments:

Theory: Usually, a decorator with arguments requires parentheses even if you use defaults (e.g., @repeat()). To make the parentheses optional, the decorator must check if the first argument it receives is a function or a configuration value.

Python
def smart_repeat(_func=None, *, count=2):

    def decorator(func):

        @wraps(func)

        def wrapper(*args, **kwargs):

            for _ in range(count):

                result = func(*args, **kwargs)

            return result

        return wrapper

    if _func is None:

        return decorator

    return decorator(_func)

@smart_repeat(count=3) # Case 1: With args

def greet(): print("Hi")

@smart_repeat # Case 2: Without args (parentheses)

def wave(): print("Wave")

Think About It: Why does a decorator with arguments require three levels of functions?
Answer: The outermost level's only job is to capture the configuration arguments and keep them in memory using a Closure. Once those are "locked in," it returns the actual decorator to wrap the function.

Theory

You can stack decorators like Lego bricks. In Python, decorators are applied from the inside out (the one closest to the function is applied first), but the execution flow behaves like an onion—you go through the outer layers to get to the core, and then pass back through them to get out.

Analogy: Dressing for Winter ❄️

1. @Coat (Top Decorator)

2. @Sweater (Bottom Decorator)

3. def Person() (The Core Function)

When the person "runs" outside, the Coat logic happens first (you put it on over everything), then the Sweater logic happens. When they come back inside (the function returns), they take off the Sweater first, then the Coat.

Code Snippets

Python

def bold_decorator(func):

    def wrapper():

        return f"<b>{func()}</b>"

    return wrapper

def italic_decorator(func):

    def wrapper():

        return f"<i>{func()}</i>"

    return wrapper

@bold_decorator

@italic_decorator

def get_text():

    return "Hello"

print(get_text()) 

# Result: <b><i>Hello</i></b>

Question: In what order do the "Before" and "After" messages print if you have two decorators?

Answer: The "Before" logic of the top decorator runs first, then the bottom one (Top $\rightarrow$ Bottom).

•The Actual Function runs.

•The "After" logic runs in reverse order, starting from the bottom decorator and moving up (Bottom $\rightarrow$ Top).

Why this matters: If you put a @timer decorator above a @logger decorator, your timer will include the time it takes for the logger to run! If you want to time only the function, the @timer should be the one closest to the function definition.

Common Mistake: 

• The Order of Operations:

Theory: Decorators are applied from the inside out. If you place a security check below a logging decorator, the system will log the access attempt before verifying if the user is allowed to enter. This can be a security risk if the log contains sensitive arguments.

Code Snippet: 

Python
def logger(func):

    def wrapper(*args, **kwargs):

        print(f"Attempting to call {func.__name__}")

        return func(*args, **kwargs)

    return wrapper

def check_admin(func):

    def wrapper(*args, **kwargs):

        if not args[0].is_admin:

            raise PermissionError("Denied!")

        return func(*args, **kwargs)

    return wrapper

#MISTAKE: Logs the attempt BEFORE checking permissions

@logger

@check_admin

def delete_database(user):

    pass

Think About It: Using the "Onion" analogy, if you want a timer to exclude the time taken by a logger, which decorator should be closer to the function?.
Answer: The @timer decorator should be closer to the function (the "core"). In Python, decorators closest to the function definition are applied first and run their "before" logic last. If the @timer is inside the @logger, the timer only starts after the logger has finished its initial setup and stops before the logger finishes its final reporting.

Edge Case Scenario:

• "Short-Circuiting" the Stack:

Theory: A decorator in a stack can decide not to call the original function (the core). If an outer decorator returns a value early (like a cached result), the inner decorators and the original function will never even run.

Code Snippet: 

Python
def cache(func):

    data = {"last": "Hello World"}

    def wrapper(*args, **kwargs):

        return data["last"] # Returns early!

    return wrapper

def slow_process(func):

    def wrapper(*args, **kwargs):

        import time

        time.sleep(10) # This will NEVER run

        return func(*args, **kwargs)

    return wrapper

@cache

@slow_process

def get_data():

    return "New Data"

Think about it: If @cache is on top, and it finds a result, does the @slow_process (the sweater) ever get "put on"?.
Answer: No. In the decorator "onion," the execution flow moves from the outermost layer to the innermost. If the top decorator (@cache) finds a result in its memory, it returns that value immediately. Because it returns early, the code never reaches the inner decorator (@slow_process), effectively skipping it entirely and saving the system from running the "slow" logic.

Theory: 

In professional engineering, we don't use decorators just to show off. We use them for Cross-Cutting Concerns. These are tasks that many different functions need to do, but they aren't part of the "core job" of the function.

For example, a function's "core job" might be to calculate a bank balance. It shouldn't also have to contain 10 lines of code to time itself or log who is calling it. We "outsource" that work to a decorator.

Case Purpose

Timer Measuring performance/speed.

Logger Tracking who accessed what data for security audits.

Retry Automatically re-running a function if the internet fails.

• Case A: The Timer (Performance Testing)

Theory: This is used to find "bottlenecks" in your code. It records the time right before the function starts and right after it ends, then calculates the difference.

Value: Identifies bottlenecks without modifying the core logic.

Code Snippets:

Python

import time

from functools import wraps

def timer(func):

    @wraps(func)

    def wrapper(*args, **kwargs):

        start_time = time.perf_counter() # Precise start time

        result = func(*args, **kwargs)

        end_time = time.perf_counter()   # Precise end time

        duration = end_time - start_time

        print(f"⏱️  {func.__name__} took {duration:.4f} seconds")

        return result

    return wrapper

@timer

def heavy_computation():

    time.sleep(1.5) # Simulating a slow process

    return "Done!"

heavy_computation()

• Case B: The Logger (Security & Auditing)  

Theory: In large apps, you need to know exactly what is happening. A Logger decorator records which function was called and what arguments were sent to it. This is vital for debugging and security.

Value: Provides an audit trail for secure or complex operations.

Code Snippets:

Python

def logger(func):

    @wraps(func)

    def wrapper(*args, **kwargs):

        print(f"Calling: {func.__name__}")

        print(f"Arguments: {args} {kwargs}")

        result = func(*args, **kwargs)

        print(f"{func.__name__} returned: {result}")

        return result

    return wrapper

@logger

def add_to_cart(item_id, quantity=1):

    return f"Added {quantity} of {item_id}"

add_to_cart("LAPTOP-123", quantity=2)

• Case C: The Retry Logic (Handling Errors)

Theory: Sometimes a function fails because of something outside your control (like a bad internet connection). Instead of letting the app crash, a Retry decorator catches the error and tries to run the function again a few times before giving up.

Pro Tip: If the function fails after the final attempt, we should re-raise the last exception. This ensures that the program doesn't continue with "bad data" and that the developer gets a proper error report.

Value: Makes the application "self-healing" against temporary network issues.

Code Snippets:

Python

from functools import wraps

def retry(times):

    def decorator(func):

        @wraps(func)

        def wrapper(*args, **kwargs):

            last_exception = None

            for i in range(times):

                try:

                    return func(*args, **kwargs)

                except Exception as e:

                    last_exception = e # Store the error to re-raise it later

                    print(f"Attempt {i+1} failed. Retrying...")

            # --- The Pro Modification ---

            print(f"All {times} attempts failed. Raising final error.")

            raise last_exception # This tells the developer EXACTLY what went wrong

        return wrapper

    return decorator

@retry(times=3)

def unstable_api_call():

    import random

    # 70% chance to fail

    if random.random() < 0.7:

        raise ConnectionError("Server is currently unreachable.")

    return "Success!"

# If this fails 3 times, it will now crash with a 'ConnectionError' 

# instead of returning a silent 'None'.

try:

    result = unstable_api_call()

    print(result)

except ConnectionError as e:

    print(f"Final Outcome: Caught the error in main code -> {e}")

Question: If you have a function that communicates with an unstable database, which of the three decorators (Timer, Logger, or Retry) is the most critical for User Experience, and which is most critical for Developer Debugging?

Answer: For User Experience: The Retry decorator is king. It allows the system to fix a "hiccup" silently without the user ever seeing an error message. To the user, it just looks like the app took an extra second to load, rather than crashing.

•For Developer Debugging: The Logger is essential. Without it, you wouldn't know why the database failed or what specific data caused the crash.

Common Mistake: 

• The "Infinite Retry" Loop:

Theory: 

When writing a Retry decorator, failing to set a maximum limit or failing to re-raise the final exception can lead to "Silent Failures". The app might keep trying forever or return None, making it impossible for the developer to know why the system eventually stopped working.

Code Snippet: 

Python

#MISTAKE: No re-raise

def brittle_retry(func):

    def wrapper(*args, **kwargs):

        for _ in range(3):

            try:

                return func(*args, **kwargs)

            except:

                print("Failed...")

        # If it reaches here, it returns None by default. CRASH LATER!

    return wrapper

Think About It: Why is raise last_exception considered the "Pro Modification" for a retry decorator?.
Answer: It ensures the application doesn't fail "silently" with bad data or a None return value after all attempts are exhausted. By re-raising the exception, the developer receives a proper error report and can debug exactly what went wrong (e.g., a ConnectionError), rather than the program continuing in an unstable state.

Edge Case Scenario:

• State-holding Decorators:

Theory: A decorator can "remember" data across multiple function calls by using variables inside the decorator's scope or by attaching attributes to the wrapper function itself.

Code Snippet: 

Python

def count_calls(func):

    @wraps(func)

    def wrapper(*args, **kwargs):

        wrapper.calls += 1 # Storing state on the function itself!

        print(f"Call number {wrapper.calls}")

        return func(*args, **kwargs)

    wrapper.calls = 0

    return wrapper

@count_calls

def say_hi():

    pass

Think About It: How is this state-holding different from using a global variable?.
Answer: State-holding in a decorator uses Encapsulation. While a global variable is "loose" and can be accidentally changed or corrupted by any other part of your script, state stored inside a decorator is "attached" directly to the function object. This keeps the data private and organized, ensuring that the count or data is only relevant to that specific decorated function and won't interfere with the rest of your program.

Theory

While we usually decorate individual functions, Python also allows us to decorate an entire class. When you place a decorator above a class definition, you are intercepting the moment the class is created.

Think of a Function Decorator like a custom skin for a single character in a game. Think of a Class Decorator like a mod for the entire game engine. It can:

•Add new methods to every object created.

•Automatically register the class in a database.

•Modify existing attributes.

•Enforce a "Singleton" pattern (ensuring only one instance of a class ever exists).

Once a class is decorated with that singleton function, it technically stops being a class and becomes a function (the get_instance wrapper).

A. Adding Attributes Automatically

This is useful for "tagging" classes so your system knows how to handle them later.

Code Snippets

Python

def add_metadata(cls):

    # We add a new attribute to the class itself

    cls.created_by = "Admin_System"

    cls.version = "1.0.4"

    return cls

@add_metadata

class UserAccount:

    def __init__(self, username):

        self.username = username

# Even though we didn't define it in the class, it's now there!
print(UserAccount.created_by) # Output: Admin_System

B. The "Singleton" Pattern (Advanced)

A Singleton ensures that no matter how many times you try to create a new object (like a Database Connection), you always get the exact same one back. This saves memory and prevents multiple conflicting connections.

Code Snippets

Python

def singleton(cls):

    instances = {} # This "remembers" the created object

    def get_instance(*args, **kwargs):

        if cls not in instances:

            instances[cls] = cls(*args, **kwargs)

        return instances[cls]

    return get_instance

@singleton

class DatabaseConnection:

    def __init__(self):

        print("--- Connecting to Database ---")

# Even though we call it twice, the print only happens ONCE!

db1 = DatabaseConnection()

db2 = DatabaseConnection()

print(db1 is db2) # Output: True (They are the exact same object in memory)

Think About It: If you decorate a class, does it affect objects that were already created before the decorator was applied?
Answer: No. Decorators run at the moment the class is defined (when the script starts). However, in Python, you usually define your classes and decorators at the top of your script, so this isn't an issue in practice.

Common Mistake: 

• Decorating "In-Place" vs. Returning:

Theory: A class decorator must return a class. If you perform modifications but forget the return cls line, your class name will suddenly become NoneType, and you won't be able to create any objects from it.

Code Snippet: 

Python
#MISTAKE

def add_id(cls):

    cls.id_enabled = True

    # Missing 'return cls'!

@add_id

class Robot:

    pass

# bot = Robot()  CRASH: TypeError: 'NoneType' object is not callable

Think About It: If a class decorator runs at the moment of definition, does it affect objects created before the script reached that line?.
Answer: No. Class decorators are executed by Python at the exact moment the class is defined (usually when the script first starts or the module is imported). Because code in a script typically runs from top to bottom, any objects created before the decorator line would have been instantiated using the original, undecorated version of the class. However, in professional practice, decorators and classes are almost always defined at the very top of a script, so this scenario is rare.

Edge Case Scenario:

• Class-Based Decorators (__call__):

Theory: You can use a Class as a decorator by implementing the __call__ magic method. This is better for complex decorators that need to maintain persistent state or multiple helper methods.

Code Snippet: 

Python
class CallCounter:

    def __init__(self, func):

        wraps(func)(self)

        self.func = func

        self.count = 0

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

        self.count += 1

        print(f"Called {self.count} times")

        return self.func(*args, **kwargs)

@CallCounter

def update_profile():

    pass

Think About It: When using a class-based decorator, when does the __init__ code run compared to the __call__ code?.
Answer: 

__init__: This runs only once at the very moment the decorator is applied to the function (when the script first starts up and defines the function). Its job is to capture the function object and set up any initial state.

__call__: This runs every single time the decorated function is actually executed by your code. This is where the "wrapper" logic lives, allowing you to perform actions before and after the original function runs.

The Scenario: You are a Lead AI Engineer building a secure banking backend. The system handles sensitive transactions and must be "bulletproof." You need to use your knowledge of Decorators to add security, performance tracking, and reliability without cluttering the core banking logic.

The Question:

1. Security Audit (Logger): Create a @log_transaction decorator that records the function name and all arguments (*args, **kwargs). Use functools.wraps to ensure the original function's name is preserved for the bank's audit trail. 

2. Performance Check (Timer): Create a @speed_test decorator that measures how long a transaction takes to process. Requirement: If you stack this with the logger, the timer must measure only the function execution, not the logging time. 

3. Reliability (Retry): Create a Configurable Decorator @retry_transfer(times=3) that attempts a bank transfer again if a ConnectionError occurs. Ensure it re-raises the final exception if all attempts fail so the developer can debug it. 

4. Resource Management (Singleton): Apply a Class Decorator to a DatabaseConnection class to ensure that only one connection object is ever created, saving the bank's server memory. 

5. Access Control (HOF): Write a Higher Order Function require_pin(func) that takes a function and returns a new version of it that asks for a 4-digit PIN before executing.

The Answer:

Python

import time

import random

from functools import wraps, lru_cache

# 1. Logger with wraps

def log_transaction(func):

    @wraps(func)

    def wrapper(*args, **kwargs):

        print(f"AUDIT: Calling {func.__name__} with {args}")

        return func(*args, **kwargs)

    return wrapper

# 2. Timer (Placed closest to function in stack)

def speed_test(func):

    @wraps(func)

    def wrapper(*args, **kwargs):

        start = time.perf_counter()

        result = func(*args, **kwargs)

        print(f"⏱️  Execution Time: {time.perf_counter() - start:.4f}s")

        return result

    return wrapper

# 3. Configurable Retry

def retry_transfer(times):

    def decorator(func):

        @wraps(func)

        def wrapper(*args, **kwargs):

            last_err = None

            for i in range(times):

                try:

                    return func(*args, **kwargs)

                except ConnectionError as e:

                    last_err = e

                    print(f"Attempt {i+1} failed. Retrying...")

            raise last_err # Re-raise final error

        return wrapper

    return decorator

# 4. Singleton Class Decorator

def singleton(cls):

    instances = {}

    def get_instance(*args, **kwargs):

        if cls not in instances:

            instances[cls] = cls(*args, **kwargs)

        return instances[cls]

    return get_instance

@singleton

class BankDatabase:

    def __init__(self):

        print("--- Opening Secure DB Connection ---")

# 5. HOF for PIN Security

def require_pin(func):

    def wrapper(*args, **kwargs):

        pin = "1234" # Mock secure PIN

        if input("Enter PIN: ") == pin:

            return func(*args, **kwargs)

        return "Access Denied"

    return wrapper

# --- Execution ---

@retry_transfer(times=2)

@log_transaction # Execution Flow: Logger -> Timer -> Core

@speed_test

def send_money(amount):

    if random.random() < 0.5:

        raise ConnectionError("Network Reset")

    return f"${amount} Sent!"

# Testing the Bank System

db1 = BankDatabase()

db2 = BankDatabase() # Won't print "Opening..." again

print(f"Same DB Connection? {db1 is db2}")

try:

    print(send_money(500))

except ConnectionError as e:

    print(f"Final Failure: {e}")

The Explanation:

1. Preserving Identity: Using @wraps(func) ensures that when the bank auditor checks send_money.__name__, it doesn't say "wrapper," which would make the logs useless. 

2. The Onion Stack: By placing @speed_test below @log_transaction, the timer starts after the log message prints, ensuring we measure the actual database speed, not the speed of the print statement. 

3. Self-Healing Code: The @retry_transfer decorator handles "hiccups" in the network. Re-raising the error with raise last_err ensures we don't return a "silent None," which could lead to money being lost in the system. 

4. Memory Efficiency: The @singleton class decorator ensures that no matter how many parts of the app need the database, they all share the same connection object, preventing the server from crashing due to too many open ports.