Decorators are one of Python's most elegant and misunderstood features. They look like magic — a single line with an @ symbol that somehow transforms the behavior of a function without changing its code. But decorators are not magic at all. They are a straightforward application of two ideas you already understand: functions are objects, and functions can accept other functions as arguments. Once those two concepts click, decorators go from mysterious to obvious. This guide builds your understanding from the ground up, starting with the prerequisites, then walking through progressively more powerful patterns until you can write production-grade decorators for logging, timing, authentication, caching, and more.
If you have ever used @staticmethod, @classmethod, or @property in a class, you have already used decorators. If you have worked with Flask and written @app.route("/home"), you have used a decorator with arguments. The goal of this guide is to take you from someone who uses decorators written by others to someone who can design and build them from scratch for any purpose.
"Functions are first-class objects in Python. They can be passed around and used as arguments just like any other object." — Guido van Rossum, creator of Python
The Prerequisites: Functions as First-Class Objects
Before you can understand decorators, you need to understand two foundational ideas. First, in Python, functions are objects. You can assign them to variables, store them in lists, pass them as arguments to other functions, and return them from other functions. Second, a function defined inside another function (called a closure) can access variables from the enclosing scope even after the outer function has finished executing. These two ideas are the entire mechanical basis of decorators.
# Functions are objects: assign to variables
def shout(text):
return text.upper()
yell = shout # No parentheses = assigning the function itself
print(yell("hello")) # HELLO
print(type(yell)) # <class 'function'>
# Functions can be passed as arguments
def apply(func, value):
"""Call any function on a value and return the result."""
return func(value)
print(apply(shout, "hello")) # HELLO
print(apply(len, "hello")) # 5
# Functions can be returned from other functions (closures)
def make_multiplier(factor):
"""Return a NEW function that multiplies by 'factor'."""
def multiplier(x):
return x * factor
return multiplier
double = make_multiplier(2)
triple = make_multiplier(3)
print(double(10)) # 20
print(triple(10)) # 30That make_multiplier example is the critical insight. The inner function multiplier remembers the value of factor from the enclosing scope, even after make_multiplier has returned. This is a closure, and it is exactly the mechanism a decorator uses to wrap one function inside another.
Your First Decorator
A decorator is a function that takes another function as input, wraps it with additional behavior, and returns the modified version. That is the entire definition. Let us build one from scratch to see every moving part.
def my_decorator(func):
"""A decorator that prints messages before and after a function call."""
def wrapper(*args, **kwargs):
print(f"--- Before calling {func.__name__} ---")
result = func(*args, **kwargs)
print(f"--- After calling {func.__name__} ---")
return result
return wrapper
# Applying the decorator manually
def say_hello(name):
"""Greet someone by name."""
print(f"Hello, {name}!")
# Wrap the function
say_hello = my_decorator(say_hello)
# Now calling say_hello actually calls wrapper
say_hello("Kandi")
# Output:
# --- Before calling say_hello ---
# Hello, Kandi!
# --- After calling say_hello ---Here is exactly what happened: my_decorator received the original say_hello function. Inside, it defined a new function called wrapper that calls the original function but adds print statements before and after. my_decorator then returned wrapper. We reassigned the name say_hello to point to wrapper. Now every call to say_hello runs the wrapper code, which in turn calls the original function. The *args and **kwargs ensure the wrapper can accept any combination of positional and keyword arguments, making it compatible with any function signature.
The @ Syntax
Writing say_hello = my_decorator(say_hello) every time is tedious and easy to forget. Python provides the @ symbol as syntactic sugar that does exactly the same thing, but at the point of function definition. Placing @my_decorator directly above a function definition is identical to calling my_decorator(say_hello) immediately after defining it.
def my_decorator(func):
def wrapper(*args, **kwargs):
print(f"--- Before calling {func.__name__} ---")
result = func(*args, **kwargs)
print(f"--- After calling {func.__name__} ---")
return result
return wrapper
# The @ syntax: clean, readable, impossible to forget
@my_decorator
def say_goodbye(name):
"""Say goodbye to someone."""
print(f"Goodbye, {name}!")
say_goodbye("Kandi")
# Output:
# --- Before calling say_goodbye ---
# Goodbye, Kandi!
# --- After calling say_goodbye ---
# This is EXACTLY equivalent to:
# def say_goodbye(name):
# print(f"Goodbye, {name}!")
# say_goodbye = my_decorator(say_goodbye)"Simple is better than complex." — Tim Peters, The Zen of Python (PEP 20)
Preserving Function Identity with functools.wraps
There is a problem with the decorator we just built. After decoration, the function's name, docstring, and other metadata are replaced by the wrapper's metadata. This breaks introspection, documentation tools, and debugging. The fix is simple: use functools.wraps, a decorator (yes, a decorator for your decorator) that copies the original function's metadata onto the wrapper.
# The problem
@my_decorator
def greet(name):
"""Display a greeting."""
print(f"Hi, {name}!")
print(greet.__name__) # wrapper (wrong!)
print(greet.__doc__) # None (wrong!)
# The solution: functools.wraps
from functools import wraps
def better_decorator(func):
@wraps(func) # Copies __name__, __doc__, __module__, etc.
def wrapper(*args, **kwargs):
print(f"--- Before calling {func.__name__} ---")
result = func(*args, **kwargs)
print(f"--- After calling {func.__name__} ---")
return result
return wrapper
@better_decorator
def greet(name):
"""Display a greeting."""
print(f"Hi, {name}!")
print(greet.__name__) # greet (correct!)
print(greet.__doc__) # Display a greeting. (correct!)Always use @functools.wraps(func) in every decorator you write. Without it, help() will show the wrapper's signature, debugging tools will display the wrong function name, and serialization libraries may fail. There is no good reason to skip it.
Decorators That Accept Arguments
Sometimes you want a decorator that is configurable. For example, a @retry(max_attempts=3) decorator or a @require_role("admin") decorator. To achieve this, you need one more layer of nesting: a factory function that accepts the arguments, and returns the actual decorator, which in turn returns the wrapper. It sounds complex, but the pattern is always the same three layers.
from functools import wraps
def repeat(n):
"""Decorator factory: repeat a function call n times."""
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
result = None
for i in range(n):
print(f" [Run {i + 1} of {n}]")
result = func(*args, **kwargs)
return result
return wrapper
return decorator
@repeat(3)
def say_hi(name):
"""Greet someone."""
print(f"Hi, {name}!")
say_hi("Kandi")
# Output:
# [Run 1 of 3]
# Hi, Kandi!
# [Run 2 of 3]
# Hi, Kandi!
# [Run 3 of 3]
# Hi, Kandi!The key to understanding the three layers is to read it from the outside in. repeat(3) is called first and returns decorator. Then decorator is applied to say_hi (just like a normal decorator) and returns wrapper. The wrapper closes over both n (from the factory) and func (from the decorator). When you call say_hi("Kandi"), you are really calling wrapper("Kandi"), which loops n times.
# A more practical example: require a specific role
def require_role(role):
"""Decorator factory: restrict function access to a specific role."""
def decorator(func):
@wraps(func)
def wrapper(user, *args, **kwargs):
if user.get("role") != role:
print(f"Access denied. '{role}' role required.")
return None
return func(user, *args, **kwargs)
return wrapper
return decorator
@require_role("admin")
def delete_database(user):
"""Dangerous operation that only admins should perform."""
print(f"{user['name']} deleted the database!")
admin = {"name": "Kandi", "role": "admin"}
guest = {"name": "Reader", "role": "viewer"}
delete_database(admin) # Kandi deleted the database!
delete_database(guest) # Access denied. 'admin' role required.When writing a decorator with arguments, remember the rule of three: outer function (receives the arguments), middle function (receives the function), inner function (receives the function's arguments). Factory → Decorator → Wrapper. Once you internalize this pattern, you can write any parameterized decorator.
Stacking Multiple Decorators
You can apply multiple decorators to a single function by stacking them. They are applied bottom-up (the decorator closest to the function is applied first), and they execute top-down when the function is called. Think of it as wrapping a gift in multiple layers of paper — the innermost layer goes on first.
from functools import wraps
import time
def log_call(func):
"""Log when a function is called."""
@wraps(func)
def wrapper(*args, **kwargs):
print(f"[LOG] Calling {func.__name__}")
return func(*args, **kwargs)
return wrapper
def timer(func):
"""Measure how long a function takes to execute."""
@wraps(func)
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = func(*args, **kwargs)
elapsed = time.perf_counter() - start
print(f"[TIMER] {func.__name__} took {elapsed:.4f}s")
return result
return wrapper
@log_call # Applied second (outermost layer)
@timer # Applied first (innermost layer)
def compute(n):
"""Compute the sum of squares up to n."""
return sum(x ** 2 for x in range(n))
result = compute(1_000_000)
# Output:
# [LOG] Calling compute
# [TIMER] compute took 0.1842sThe stacking order matters. In the example above, timer is applied to compute first, creating a timed version. Then log_call is applied to that timed version, adding logging around the entire package. When you call compute(), the log fires first, then the timer starts, then the original function runs, then the timer stops, and finally the log is complete. Reversing the order would change the timing to include the logging overhead.
Real-World Decorator Patterns
Now that you understand the mechanics, let us build decorators you would actually use in production code. These patterns appear in web frameworks, APIs, CLI tools, and system administration scripts every day.
Timing and Performance
from functools import wraps
import time
def timer(func):
"""Measure and print execution time."""
@wraps(func)
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = func(*args, **kwargs)
elapsed = time.perf_counter() - start
print(f"{func.__name__} completed in {elapsed:.4f}s")
return result
return wrapper
@timer
def fetch_data():
"""Simulate a slow network call."""
time.sleep(1.2)
return {"status": "ok"}
data = fetch_data() # fetch_data completed in 1.2004sAutomatic Retry on Failure
import time
import random
from functools import wraps
def retry(max_attempts=3, delay=1):
"""Retry a function if it raises an exception."""
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
for attempt in range(1, max_attempts + 1):
try:
return func(*args, **kwargs)
except Exception as e:
print(f" Attempt {attempt}/{max_attempts} failed: {e}")
if attempt < max_attempts:
time.sleep(delay)
raise Exception(f"{func.__name__} failed after {max_attempts} attempts")
return wrapper
return decorator
@retry(max_attempts=3, delay=0.5)
def unstable_api_call():
"""Simulate an API that fails randomly."""
if random.random() < 0.7:
raise ConnectionError("Server unavailable")
return {"data": "success"}
try:
result = unstable_api_call()
print(f"Got: {result}")
except Exception as e:
print(e)Caching (Memoization)
from functools import wraps
def cache(func):
"""Cache the results of a function based on its arguments."""
memo = {}
@wraps(func)
def wrapper(*args):
if args in memo:
print(f" [CACHE HIT] {func.__name__}{args}")
return memo[args]
print(f" [CACHE MISS] {func.__name__}{args}")
result = func(*args)
memo[args] = result
return result
return wrapper
@cache
def fibonacci(n):
"""Compute the nth Fibonacci number recursively."""
if n < 2:
return n
return fibonacci(n - 1) + fibonacci(n - 2)
print(fibonacci(10)) # 55 (most calls are cache hits)
print(fibonacci(10)) # 55 (entire result is cached)"Don't repeat yourself. Every piece of knowledge must have a single, unambiguous, authoritative representation within a system." — Andy Hunt and Dave Thomas, The Pragmatic Programmer
Python's standard library already provides @functools.lru_cache, which is a battle-tested, thread-safe caching decorator with a configurable maximum size. Use it instead of writing your own cache for production code: @lru_cache(maxsize=128). The example above is for understanding how caching decorators work internally.
Logging with Context
from functools import wraps
from datetime import datetime
def audit_log(func):
"""Log every function call with timestamp and arguments."""
@wraps(func)
def wrapper(*args, **kwargs):
timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
args_repr = [repr(a) for a in args]
kwargs_repr = [f"{k}={v!r}" for k, v in kwargs.items()]
signature = ", ".join(args_repr + kwargs_repr)
print(f"[{timestamp}] CALL {func.__name__}({signature})")
result = func(*args, **kwargs)
print(f"[{timestamp}] RETURN {func.__name__} -> {result!r}")
return result
return wrapper
@audit_log
def transfer_funds(from_acct, to_acct, amount):
"""Transfer money between accounts."""
return {"status": "completed", "amount": amount}
transfer_funds("ACC-001", "ACC-002", amount=250.00)
# [2026-02-13 10:30:45] CALL transfer_funds('ACC-001', 'ACC-002', amount=250.0)
# [2026-02-13 10:30:45] RETURN transfer_funds -> {'status': 'completed', 'amount': 250.0}Class-Based Decorators
Any callable object can be a decorator, not just functions. By implementing the __call__ method on a class, you can create decorators that carry state between calls. This is useful when you need to track how many times a function has been called, enforce rate limits, or accumulate data across invocations.
from functools import wraps
class CountCalls:
"""Decorator that counts how many times a function is called."""
def __init__(self, func):
wraps(func)(self)
self.func = func
self.call_count = 0
def __call__(self, *args, **kwargs):
self.call_count += 1
print(f" [{self.func.__name__}] Call #{self.call_count}")
return self.func(*args, **kwargs)
@CountCalls
def process_request(endpoint):
"""Handle an incoming request."""
return f"200 OK: {endpoint}"
process_request("/home") # [process_request] Call #1
process_request("/about") # [process_request] Call #2
process_request("/api/data") # [process_request] Call #3
print(f"Total calls: {process_request.call_count}") # 3class RateLimit:
"""Decorator that enforces a maximum number of calls per time window."""
def __init__(self, max_calls, period_seconds):
self.max_calls = max_calls
self.period = period_seconds
self.calls = []
def __call__(self, func):
@wraps(func)
def wrapper(*args, **kwargs):
import time
now = time.time()
# Remove calls outside the window
self.calls = [t for t in self.calls if now - t < self.period]
if len(self.calls) >= self.max_calls:
wait = self.period - (now - self.calls[0])
print(f"Rate limited. Try again in {wait:.1f}s")
return None
self.calls.append(now)
return func(*args, **kwargs)
return wrapper
@RateLimit(max_calls=3, period_seconds=10)
def api_request(endpoint):
"""Make an API request."""
return f"Response from {endpoint}"
# First three calls succeed; the fourth is rate-limited
for i in range(5):
result = api_request(f"/endpoint-{i}")
print(result)"Programs must be written for people to read, and only incidentally for machines to execute." — Harold Abelson, Structure and Interpretation of Computer Programs
Built-In Decorators You Should Know
Python's standard library and built-in functions include several decorators that you will encounter and use regularly. Understanding what they do will make you a more effective Python developer.
from functools import lru_cache
# @staticmethod - method that doesn't access instance or class
class MathUtils:
@staticmethod
def add(a, b):
return a + b
print(MathUtils.add(3, 5)) # 8
# @classmethod - method that receives the class, not the instance
class User:
def __init__(self, name, role):
self.name = name
self.role = role
@classmethod
def admin(cls, name):
"""Factory method to create an admin user."""
return cls(name, "admin")
admin = User.admin("Kandi")
print(f"{admin.name}: {admin.role}") # Kandi: admin
# @property - access a method like an attribute
class Circle:
def __init__(self, radius):
self._radius = radius
@property
def area(self):
"""Calculate area on demand."""
import math
return math.pi * self._radius ** 2
@property
def radius(self):
return self._radius
@radius.setter
def radius(self, value):
if value < 0:
raise ValueError("Radius cannot be negative")
self._radius = value
c = Circle(5)
print(f"Area: {c.area:.2f}") # Area: 78.54
c.radius = 10
print(f"Area: {c.area:.2f}") # Area: 314.16
# @lru_cache - production-grade memoization
@lru_cache(maxsize=256)
def expensive_computation(n):
"""Simulate a slow calculation."""
return sum(i ** 2 for i in range(n))
print(expensive_computation(10000)) # Computed
print(expensive_computation(10000)) # Instant (cached)
print(expensive_computation.cache_info())In Python 3.9+, you can use @functools.cache as a simpler alternative to @lru_cache(maxsize=None). It provides unlimited caching with a cleaner syntax. For functions where the argument space is bounded and you want every result cached permanently, @cache is the cleanest option.
Key Takeaways
- Decorators are functions that wrap functions: They take a function as input, define a wrapper that adds behavior, and return the wrapper. The
@decoratorsyntax is shorthand forfunc = decorator(func). - The foundation is closures: Functions are first-class objects in Python. Inner functions can close over variables from enclosing scopes. This is the mechanism that makes decorators work.
- Always use @functools.wraps: Without it, your decorated function loses its name, docstring, and metadata. There is no excuse for omitting it.
- Parameterized decorators need three layers: Factory (receives arguments) → Decorator (receives function) → Wrapper (receives function arguments). The pattern is always the same.
- Stacking order matters: Decorators are applied bottom-up and execute top-down. The decorator closest to the function definition wraps it first.
- Real-world uses are everywhere: Timing, logging, caching, retrying, authentication, rate limiting, and input validation are all natural fits for decorators. They keep cross-cutting concerns separate from business logic.
- Know the built-ins:
@staticmethod,@classmethod,@property, and@functools.lru_cacheare decorators you will use in almost every Python project.
Decorators embody one of programming's most important principles: separation of concerns. They let you write your core logic cleanly and then layer on cross-cutting functionality — logging, security, performance — without muddying the original code. Once you can read, write, and debug decorators fluently, you will have unlocked one of the most powerful design tools Python has to offer.