What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
What does the @ symbol above a Python function do? It applies a decorator to the function object created by the definition, then binds the decorator’s result to the function’s name. In the common “gift wrapper” pattern, that result is a new callable that adds behavior before or after calling the original function—but decorators can return other objects, too.
What a Python decorator does
A function definition creates a function object. When its decorator expressions are evaluated, Python applies them to that object; the name is then bound to the result. A useful mental model is function_name = decorator(function_name). This is an equivalent assignment model for understanding the syntax, not a claim that Python literally rewrites the source code into that line.
As an Amazon Associate I earn from qualifying purchases.
The Python 3.14 Language Reference says, “A function definition may be wrapped by one or more decorator expressions.” In ordinary use, a decorator is a callable that receives the defined object and returns the object that will be bound to the name. It may return a wrapper, another callable, or even a different kind of object.
How the gift-wrapper pattern works
Imagine the function as a gift and the decorator as an extra layer around how it is presented or used. In a common implementation, the decorator returns a wrapper function. The wrapper can do work before and after it delegates to the original function, pass through the original arguments, and return the original call’s result.
#1 Best Overall
from functools import wraps
def announce(func):
@wraps(func)
def wrapper(*args, **kwargs):
print("Starting")
result = func(*args, **kwargs)
print("Finished")
return result
return wrapper
@announce
def greet(name):
return f"Hello, {name}!"When Python executes the decorated definition, announce receives the function object for greet. It returns wrapper, which becomes the object bound to the name greet. Later, calling greet("Ada") calls that wrapper: it prints “Starting,” calls the original function with "Ada", prints “Finished,” and returns the greeting string.
What happens at definition time versus call time
These are separate stages. The decorator is applied when execution reaches the decorated definition. Code in the decorator itself runs at that stage. Code inside the returned wrapper runs later, each time the decorated name is called. In the example, constructing the wrapper happens during decoration; the two messages and the call to the original function happen when greet is called.
How decorator syntax relates to assignment
The basic syntax is equivalent in effect to defining the function and then applying the decorator to it:
def greet(name):
return f"Hello, {name}!"
greet = announce(greet)This equivalent form makes the binding clear: after decoration, the name refers to whatever announce returned. It is a way to understand the syntax, not a recommendation to rewrite decorated definitions manually.
How stacked decorators are applied
When decorators are stacked, the one closest to def is applied first. For @outer above @inner, the result is conceptually outer(inner(work)):
@outer
@inner
def work():
...
# Conceptually:
work = outer(inner(work))First, inner receives the original function and returns an object. Then outer receives that result. When the name work is called later, execution proceeds through the object returned by outer.
How decorators with arguments work
A form such as @repeat(3) uses a decorator factory: repeat(3) runs first and returns a decorator. That returned decorator then receives the function object. The integer 3 configures the factory; it is not passed directly to the function being decorated.
@repeat(3)
def wave():
...Its conceptual shape is decorator = repeat(3), followed by wave = decorator(wave). This extra stage lets the factory capture configuration for use by the decorator or the wrapper it creates.
Why wrapper decorators use functools.wraps
A wrapper is a new function, so without help it can expose its own name and docstring rather than the original function’s. The standard-library functools.wraps decorator copies useful metadata from the wrapped callable and provides the original through the wrapper’s __wrapped__ attribute. Use it on the inner wrapper in ordinary wrapper decorators, as in the announce example.
Quick Recap
Two practical details that prevent common bugs
- Return the wrapped call’s result. If the wrapper calls the original but omits
return result, callers receiveNoneinstead of the original function’s return value. - Keep the stages straight. Decoration transforms the object bound to a name; a wrapper’s body runs on calls. Not every decorator returns a wrapper or calls the original function.
Sources
- Python 3.14 Language Reference: Compound statements
- PEP 318: Decorators for Functions and Methods (historical proposal and equivalence examples)
- Python 3.14.8 standard-library documentation: functools
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
