Python Decorators Explained — How, Why, and When to Use Them

# Demonstrating that functions are objects in Python
# This is the foundation that makes decorators possible

def say_good_morning(name):
    return f"Good morning, {name}!"

# Assign the function to a new variable — no parentheses, we're not calling it
greeting_function = say_good_morning

# Both names point to the same function object
print(greeting_function("Alice"))   # Works exactly like the original
print(say_good_morning("Alice"))    # Same output

# Functions can be passed as arguments
def run_twice(func, value):
    """Accepts a function and calls it twice with the same value."""
    first_result = func(value)
    second_result = func(value)
    return first_result, second_result

results = run_twice(say_good_morning, "Bob")
print(results)

# Functions can be returned from other functions
def get_greeter():
    """Returns a function — note we return the function object, not its result."""
    def say_hello(name):
        return f"Hello, {name}!"
    return say_hello   # No parentheses — returning the function itself

created_greeter = get_greeter()
print(created_greeter("Carol"))     # Call the returned function
print(type(created_greeter))        # It really is a function object

import time
import functools

# This is our decorator — a function that accepts a function
def measure_execution_time(original_function):
    """
    A decorator that prints how long the decorated function took to run.
    Works with any function regardless of its arguments or return value.
    """

    # functools.wraps copies the original function's metadata onto the wrapper
    # Without this, original_function.__name__ would return 'wrapper' — a silent bug
    @functools.wraps(original_function)
    def wrapper(*args, **kwargs):      # *args/**kwargs lets us accept ANY function signature
        start_time = time.perf_counter()              # High-resolution timer

        result = original_function(*args, **kwargs)   # Call the real function, capture result

        end_time = time.perf_counter()
        duration_ms = (end_time - start_time) * 1000  # Convert to milliseconds

        print(f"[TIMER] {original_function.__name__} completed in {duration_ms:.2f}ms")

        return result    # Always return the original result — don't swallow it!

    return wrapper       # Return the wrapper, NOT wrapper() — return the object, not the call


# Apply the decorator — Python now does: fetch_user_data = measure_execution_time(fetch_user_data)
@measure_execution_time
def fetch_user_data(user_id):
    """Simulates a database lookup with a small delay."""
    time.sleep(0.05)   # Simulate 50ms database query
    return {"id": user_id, "name": "Alice", "role": "admin"}


@measure_execution_time
def calculate_monthly_report(year, month, include_tax=True):
    """Simulates a heavy report calculation."""
    time.sleep(0.1)    # Simulate 100ms computation
    return {"year": year, "month": month, "total": 48250.75}


# These calls look completely normal — the timing is invisible to the caller
user = fetch_user_data(42)
print(f"Got user: {user['name']}\n")

report = calculate_monthly_report(2024, 6, include_tax=True)
print(f"Report total: ${report['total']}")

import time
import functools

# LAYER 1: The factory — accepts the configuration, returns a decorator
def retry(max_attempts=3, delay_seconds=1.0, exceptions_to_catch=(Exception,)):
    """
    A configurable retry decorator.
    max_attempts: how many times to try before giving up
    delay_seconds: how long to wait between attempts
    exceptions_to_catch: only retry on these specific exception types
    """

    # LAYER 2: The actual decorator — accepts the function to wrap
    def decorator(original_function):

        # LAYER 3: The wrapper — runs every time the decorated function is called
        @functools.wraps(original_function)
        def wrapper(*args, **kwargs):
            last_exception = None

            for attempt_number in range(1, max_attempts + 1):
                try:
                    print(f"  Attempt {attempt_number}/{max_attempts} for '{original_function.__name__}'")
                    result = original_function(*args, **kwargs)   # Try the actual call
                    print(f"  Success on attempt {attempt_number}!")
                    return result    # It worked — return immediately

                except exceptions_to_catch as error:
                    last_exception = error
                    print(f"  Failed: {error}")

                    # Don't sleep after the final attempt — pointless to wait then give up
                    if attempt_number < max_attempts:
                        time.sleep(delay_seconds)

            # All attempts exhausted — re-raise the last error
            raise RuntimeError(
                f"'{original_function.__name__}' failed after {max_attempts} attempts. "
                f"Last error: {last_exception}"
            )

        return wrapper   # Decorator returns the wrapper
    return decorator     # Factory returns the decorator


# --- Simulate an unreliable external API ---
call_counter = 0

@retry(max_attempts=3, delay_seconds=0.1, exceptions_to_catch=(ConnectionError,))
def fetch_weather_data(city):
    """Simulates a flaky HTTP call that succeeds on the 3rd attempt."""
    global call_counter
    call_counter += 1

    if call_counter < 3:
        raise ConnectionError(f"Connection timed out reaching weather API (call #{call_counter})")

    return {"city": city, "temperature_c": 22, "condition": "Sunny"}


# Usage is clean — the retry logic is completely invisible here
print("Fetching weather...")
weather = fetch_weather_data("London")
print(f"\nFinal result: {weather['city']} is {weather['temperature_c']}°C and {weather['condition']}")

# Verify functools.wraps preserved the function name
print(f"\nFunction name preserved: {fetch_weather_data.__name__}")

import functools

# --- Simulated session store (in real life this would be a database or Redis) ---
active_sessions = {
    "token_abc123": {"user_id": 7, "username": "alice", "role": "admin"},
    "token_xyz789": {"user_id": 12, "username": "bob",   "role": "viewer"},
}


def require_authentication(required_role=None):
    """
    Decorator factory that guards a function behind session authentication.
    Optionally enforces a specific role (e.g., 'admin').
    """
    def decorator(original_function):
        @functools.wraps(original_function)
        def wrapper(session_token, *args, **kwargs):
            # Step 1: Check if the token exists in active sessions
            session = active_sessions.get(session_token)

            if session is None:
                # Abort immediately — don't call the original function at all
                return {"error": "Unauthorised. Invalid or expired session token.", "status": 401}

            # Step 2: If a role is required, check it
            if required_role and session["role"] != required_role:
                return {
                    "error": f"Forbidden. Requires role '{required_role}', got '{session['role']}'.",
                    "status": 403
                }

            # Step 3: Inject the session data as a keyword argument — the function can use it
            kwargs["current_user"] = session

            # Step 4: All checks passed — call the real function
            return original_function(session_token, *args, **kwargs)

        return wrapper
    return decorator


# Any authenticated user can view their own profile
@require_authentication()
def get_user_profile(session_token, **kwargs):
    user = kwargs["current_user"]
    return {"status": 200, "profile": {"username": user["username"], "role": user["role"]}}


# Only admins can delete accounts
@require_authentication(required_role="admin")
def delete_user_account(session_token, target_user_id, **kwargs):
    admin = kwargs["current_user"]
    return {"status": 200, "message": f"Account {target_user_id} deleted by {admin['username']}"}


# --- Test the decorator with different scenarios ---
print("=== Valid admin token ===")
print(get_user_profile("token_abc123"))
print(delete_user_account("token_abc123", target_user_id=99))

print("\n=== Valid viewer token (no admin rights) ===")
print(get_user_profile("token_xyz789"))
print(delete_user_account("token_xyz789", target_user_id=99))

print("\n=== Invalid token ===")
print(get_user_profile("token_fake999"))