Appearance
3.13.4 — Scope, Functions & Closures
A checkout module keeps a running count of orders in a variable called orders_seen. A new function adds one line, orders_seen += 1, and crashes with UnboundLocalError even though orders_seen clearly exists two lines above it. The same week, a helper that builds order lines starts returning yesterday's items mixed into today's orders. Both bugs come from how Python decides what a name means and when a function's pieces are created. This page covers both: the scope rules, every kind of parameter, default values, closures, and the small tools built on top of them. Everything here is also the foundation for decorators in 3.13.5 and for how FastAPI reads your functions in Chapter 3.14.
1. How Python finds a name: LEGB
When Python meets a name like tax_rate, it searches four places, in a fixed order. The order is called LEGB, after the first letters of the four places.
- Local. The current function's own variables.
- Enclosing. The variables of any function that this function is written inside, from the nearest outwards.
- Global. The variables at the top level of the current module.
- Built-in. Python's own names, such as
len,printandValueError.
The first place that has the name wins. If none has it, you get a NameError.
python
tax_rate = 0.18 # (1) global
def total_with_tax(amount): # (2) amount is local
return amount * (1 + tax_rate) # (3)
print(total_with_tax(100))text
118.0(1)tax_ratelives in the module's global scope.(2)amountis a parameter, so it is local to the function.(3)Python looks fortax_ratein the local scope, does not find it, has no enclosing function to check, and finds it in the global scope.
The built-in scope is just a module called builtins. When you call len, Python finds builtins.len at the end of the search. This is also why naming your own variable list or id is a bad idea: your global name is found first, and the built-in is hidden for the rest of the module.
Only functions create scopes
In many languages, every { } block creates a scope. In Python, only functions, classes and modules create scopes. An if block or a for loop does not.
python
for i in range(3):
pass
print(i) # (1)
squares = [n * n for n in range(3)]
try:
print(n) # (2)
except NameError as error:
print("NameError:", error)text
2
NameError: name 'n' is not defined(1)The loop variable still exists after the loop, holding its last value.(2)A comprehension is different. It has its own small scope, sondoes not leak out. Python 3 made that change deliberately, because leaking loop variables from comprehensions caused real bugs in Python 2.
2. The UnboundLocalError puzzle
Now the opening bug.
python
orders_seen = 0
def record_order():
orders_seen += 1 # (1)
try:
record_order()
except UnboundLocalError as error:
print("UnboundLocalError:", error)text
UnboundLocalError: cannot access local variable 'orders_seen' where it is not associated with a value(1)This line readsorders_seenand then assigns to it.
Why does it fail? The answer is in when Python decides scope. It does not decide while the function runs. It decides when the function is compiled, by looking at the whole body at once. The rule is:
If a function assigns to a name anywhere in its body, that name is local to the whole function.
orders_seen += 1 is an assignment. So the compiler marks orders_seen as local everywhere in record_order. When the line runs, it first tries to read the local orders_seen, which has not been given a value yet. Hence the error. The global variable is never even consulted.
You can see the compiler's decision in the bytecode. A local variable is read with LOAD_FAST, a global with LOAD_GLOBAL. The function above uses LOAD_FAST for orders_seen.
This rule exists for a good reason. If Python decided scope line by line, the same name in the same function could mean the global on one line and a local on the next, depending on which branch had run. Deciding once, for the whole function, makes every name mean one thing.
global and nonlocal
You fix the puzzle by telling the compiler what you mean.
python
orders_seen = 0
def record_order():
global orders_seen # (1)
orders_seen += 1
record_order()
record_order()
print(orders_seen)text
2(1)globalsays "this name refers to the module-level variable, even though I assign to it here".
nonlocal does the same for a variable in an enclosing function, which section 5 uses. In real code, global is usually a sign of a design problem. Shared state is better held in an object, or passed in and returned. You will see nonlocal far more often, inside closures.
3. Functions are objects
A def statement is not a declaration. It is a statement that runs. When Python executes it, it creates a new function object and binds it to the name. Like every object from 3.13.2, a function can be stored in a variable, put in a list, passed to another function, returned from a function and given attributes.
python
def describe(price: float, qty: int = 1) -> str:
"""Return one line for the receipt."""
return f"{qty} x {price}"
print(type(describe)) # (1)
print(describe.__name__) # (2)
print(describe.__doc__) # (3)
print(describe.__defaults__) # (4)
print(describe.__annotations__) # (5)text
<class 'function'>
describe
Return one line for the receipt.
(1,)
{'price': <class 'float'>, 'qty': <class 'int'>, 'return': <class 'str'>}(1)It is an ordinary object of typefunction.(2)It remembers its own name.(3)The string at the top of the body is the docstring, stored for help tools and documentation.(4)Default values are stored on the function object. This fact causes the bug in section 4.(5)Type hints are stored too, in__annotations__. Python itself ignores them, but tools read them. FastAPI reads exactly this information to decide what each parameter means (3.13.12).
A function object is a thin wrapper. It holds a pointer to a code object from 3.13.1, which has the bytecode, plus the things that can differ between functions made from the same code: the defaults, the globals dict to use, and any closure cells.
Because functions are values, Python code passes them around all the time. Here is the most common case, sorting with a key function.
python
orders = [{"id": 1, "total": 300}, {"id": 2, "total": 120}]
cheapest_first = sorted(orders, key=lambda order: order["total"]) # (1)
print(cheapest_first)
from operator import itemgetter
print(max(orders, key=itemgetter("total"))) # (2)text
[{'id': 2, 'total': 120}, {'id': 1, 'total': 300}]
{'id': 1, 'total': 300}(1)sortedcalls the key function once for each item and sorts by what it returns.(2)operator.itemgetter("total")builds the same kind of function without alambda, and runs a little faster because it is written in C.
A lambda is simply a function with no name whose body is a single expression. lambda order: order["total"] is the same as a def that returns order["total"]. Use it for tiny throwaway functions like this one. If it needs a name, a docstring or more than one line, write a def.
4. Every kind of parameter
Python has five kinds of parameter, and one function can use all of them. Learning them properly matters, because library code, decorators and FastAPI's routing all rely on them.
python
def create_order(sku, /, qty=1, *extras, express=False, **meta): # (1)
return sku, qty, extras, express, meta
print(create_order("mug", 2, "gift-wrap", express=True, source="app"))text
('mug', 2, ('gift-wrap',), True, {'source': 'app'})(1)Read the signature from left to right.skucomes before the/, so it is positional-only. You must pass it by position.qty=1is a normal parameter. You can pass it by position or by name, and it has a default.*extrascollects any extra positional arguments into a tuple.express=Falsecomes after the*extras, so it is keyword-only. You must writeexpress=Trueby name.**metacollects any extra keyword arguments into a dict.
The standard library can list these kinds for you. This is exactly how frameworks inspect your functions.
python
import inspect
def create_order(sku, /, qty=1, *extras, express=False, **meta):
pass
for param in inspect.signature(create_order).parameters.values():
print(param.name, param.kind.name)text
sku POSITIONAL_ONLY
qty POSITIONAL_OR_KEYWORD
extras VAR_POSITIONAL
express KEYWORD_ONLY
meta VAR_KEYWORDWhy keyword-only parameters exist
Look at this call: ship(4417, "dhl", True, False). What do True and False mean? Nobody can tell without opening the function. Keyword-only parameters force the caller to write the name, so every call explains itself. You make them with a bare *, which means "no more positional arguments after this point".
python
def ship(order_id, *, carrier, insured=False): # (1)
return order_id, carrier, insured
print(ship(4417, carrier="dhl", insured=True))
try:
ship(4417, "dhl") # (2)
except TypeError as error:
print("TypeError:", error)text
(4417, 'dhl', True)
TypeError: ship() takes 1 positional argument but 2 were given(1)The bare*collects nothing. It only marks everything after it as keyword-only.(2)Passing the carrier by position is refused.
Use keyword-only parameters for flags and options. It also lets you add or reorder options later without breaking callers.
Why positional-only parameters exist
Positional-only parameters, added in Python 3.8, solve the opposite problem. Sometimes the parameter's name is not part of the promise you make to callers. If callers cannot use the name, you can rename it later without breaking anyone. Many built-ins already worked this way. You cannot write len(obj=items).
python
def lookup(sku, /, warehouse="main"):
return sku, warehouse
try:
lookup(sku="mug")
except TypeError as error:
print("TypeError:", error)text
TypeError: lookup() got some positional-only arguments passed as keyword arguments: 'sku'There is a second use. A function that also takes **kwargs can now accept a keyword with the same name as a positional-only parameter, because the two can no longer clash.
python
def html_tag(name, /, **attributes): # (1)
return name, attributes
print(html_tag("form", name="checkout")) # (2)text
('form', {'name': 'checkout'})(1)nameis positional-only.(2)Soname="checkout"is free to go intoattributes. Without the/, Python would complain thatnamewas given twice.
Unpacking arguments at the call site
The * and ** symbols also work in the other direction, when calling a function. * spreads a sequence into positional arguments, and ** spreads a dict into keyword arguments.
python
def ship(order_id, *, carrier, insured=False):
return order_id, carrier, insured
options = {"carrier": "bluedart", "insured": True}
print(ship(*[4417], **options)) # (1)text
(4417, 'bluedart', True)(1)The list supplies the positional argument and the dict supplies the keywords.
This is how decorators forward "whatever arguments I was given" to the function they wrap, as you will see in 3.13.5.
The mutable default argument trap
Now the second bug from the opening: order lines from one call leaking into the next.
python
def add_line(item, lines=[]): # (1)
lines.append(item)
return lines
print(add_line("mug"))
print(add_line("pen")) # (2)
print(add_line.__defaults__) # (3)text
['mug']
['mug', 'pen']
(['mug', 'pen'],)(1)The default[]is evaluated once, when thedefstatement runs, and stored on the function object.(2)The second call did not get a fresh list. It got the same list as the first call, which already held"mug".(3)You can see the shared list sitting on the function, growing with each call.
This follows straight from two facts you already know. def runs once and stores its defaults. And a default is a label on an object, not a recipe for making one. Every call that uses the default gets a label on that one stored list.
The fix is a pattern every Python developer knows by heart: use None as the default, and create the list inside the body.
python
def add_line(item, lines=None):
if lines is None: # (1)
lines = [] # (2)
lines.append(item)
return lines
print(add_line("mug"), add_line("pen"))text
['mug'] ['pen'](1)Noneis immutable and a singleton, so sharing it is harmless.(2)The body runs on every call, so every call gets a brand-new list.
The same trap catches dicts, sets and any mutable object, and also defaults like created_at=datetime.now(). That timestamp is the time the module was imported, frozen forever. The 3.13.8 dataclass and 3.14.2 Pydantic pages show how those tools solve the same problem with default_factory.
5. Closures
A closure is a function that remembers variables from the function it was created in, even after that outer function has returned. You met the same idea in JavaScript in 3.6.2. Python's version works on the same principle with different machinery.
python
def make_order_counter():
count = 0 # (1)
def next_order_id():
nonlocal count # (2)
count += 1
return count
return next_order_id # (3)
next_id = make_order_counter()
print(next_id(), next_id(), next_id()) # (4)text
1 2 3(1)countis a local variable of the outer function.(2)nonlocaltells the compiler thatcountbelongs to the enclosing function. Without it,count += 1would makecountlocal and fail with the sameUnboundLocalErroras before.(3)The outer function returns the inner function object and then ends.(4)The inner function still has access tocount, and its value survives between calls.
How it works: cells
How can count survive after make_order_counter has returned? A normal local variable lives in a numbered slot in the function's frame, and the frame is thrown away on return.
The compiler sees that an inner function uses count. So it does not store count in a plain slot. It stores it in a cell: a tiny separate object whose only job is to hold one value. Both functions hold a pointer to the same cell. When the outer function returns, its frame is discarded, but the cell lives on, because the inner function still points at it.
You can look at the cell directly.
python
def make_order_counter():
count = 0
def next_order_id():
nonlocal count
count += 1
return count
return next_order_id
next_id = make_order_counter()
next_id(); next_id(); next_id()
print(make_order_counter.__code__.co_cellvars) # (1)
print(next_id.__code__.co_freevars) # (2)
print(next_id.__closure__[0].cell_contents) # (3)text
('count',)
('count',)
3(1)The outer function's code records thatcountmust be stored in a cell.(2)The inner function's code recordscountas a free variable: a name it uses that belongs to an enclosing function.(3)__closure__is the tuple of cells the inner function carries. The one cell holds the current value, 3.
In the bytecode, reading and writing a cell uses LOAD_DEREF and STORE_DEREF, where "deref" means "follow the pointer into the cell". So the compiler uses three different instructions for the three kinds of name: LOAD_FAST for locals, LOAD_DEREF for closure variables and LOAD_GLOBAL for globals.
The late-binding trap
Closures remember variables, not values. Python looks up the variable's value when the inner function runs, not when it is created. This causes a famous bug.
python
handlers = [lambda: n for n in range(3)] # (1)
print([handler() for handler in handlers])
handlers = [lambda n=n: n for n in range(3)] # (2)
print([handler() for handler in handlers])text
[2, 2, 2]
[0, 1, 2](1)All three lambdas close over the same variablen. By the time any of them runs, the loop has finished andnis 2. So all three return 2.(2)The fix copies the current value into a default parameter. Defaults are evaluated when the lambda is created, so each lambda captures its own value.functools.partialis a clearer way to do the same thing.
This is the Python twin of JavaScript's var-in-a-loop trap from 3.6.2. JavaScript fixed it with let, which makes a new variable on every loop turn. Python has no such keyword, so you use the default-argument trick or partial.
What closures are used for
Closures give you private state without a class. Real uses include:
- Counters and ID generators, like the example above.
- Configured functions.
make_discount(percent=30)returns a function that applies 30%. - Callbacks that need to remember context, such as which order a button belongs to.
- Decorators, which are the whole of 3.13.5. Every decorator you have ever used is a closure.
When the state grows past one or two variables, or you need several operations on it, a class is usually clearer. A closure and an object with one method are two ways of writing the same thing.
6. functools.partial: freezing some arguments
partial takes a function and some of its arguments, and returns a new callable with those arguments already filled in.
python
from functools import partial
def apply_discount(amount, percent):
return amount * (100 - percent) / 100
staff_price = partial(apply_discount, percent=30) # (1)
print(staff_price(200)) # (2)
print(staff_price.func.__name__, staff_price.keywords) # (3)text
140.0
apply_discount {'percent': 30}(1)staff_priceisapply_discountwithpercentfixed at 30.(2)Calling it supplies the remaining argument.(3)Unlike a lambda, apartialobject shows you what it wraps and which arguments it fixed. That makes it easier to read in a debugger or a log.
You will use partial whenever an API wants a function of one argument, but your function needs two. Examples include callbacks, map, thread pools and FastAPI dependencies.
What the interviewer will push on
"Why does count += 1 inside a function raise UnboundLocalError when count is a global?" They are checking whether you know scope is decided at compile time. Any assignment makes the name local to the whole function, so the read part of += looks at an empty local. Fix with global, or better, by not sharing mutable module state. The common wrong answer is "Python cannot read globals inside functions", which is false. Reading is fine. Assigning changes the scope.
"What is wrong with def f(items=[])?" The default is evaluated once, when def runs, so every call shares one list. Use None and create the list inside. The tell of a strong answer is explaining why: defaults live on the function object in __defaults__, and def is a statement that runs once.
"What is a closure in Python, and how is it implemented?" A function that keeps access to variables of the enclosing function after it returns. The implementation answer is what separates people: the shared variable is stored in a cell object, the inner function carries those cells in __closure__, and the bytecode uses LOAD_DEREF. Mention nonlocal for rebinding.
"What does [lambda: i for i in range(3)] return when called?" All 2s, because closures capture variables, not values, and the lookup happens at call time. Fix with lambda i=i: i or functools.partial.
"Explain / and * in a function signature." Before / is positional-only, after * is keyword-only. Give the real reasons: keyword-only makes boolean flags readable at the call site, and positional-only lets a library rename a parameter without breaking callers.
Something to volunteer that nobody asks for: inspect.signature exposes all five parameter kinds, plus annotations and defaults. That is precisely how FastAPI decides whether each parameter is a path value, a query string or a request body. Knowing that makes FastAPI feel obvious instead of magical.
Recall
- Name lookup follows LEGB: local, enclosing, global, built-in. Only functions, classes and modules create scopes. Loop variables leak out of
forloops but not out of comprehensions. - Scope is decided at compile time. Any assignment to a name makes it local for the whole function, which causes
UnboundLocalError.globalandnonlocalchange that decision. defruns and creates a function object holding a code object,__defaults__,__annotations__, a docstring and closure cells.- Five parameter kinds: positional-only (before
/), normal,*args, keyword-only (after*or*args),**kwargs.inspect.signaturelists them. - Defaults are evaluated once. Never use a mutable default. Use
Noneand build the object inside. - A closure keeps variables from its enclosing function in cells (
__closure__,co_freevars,LOAD_DEREF). Closures capture variables, not values, so loop lambdas needi=iorpartial. functools.partialfreezes some arguments and stays inspectable.
Self-test: Why does the compiler, not the running code, decide that a name is local? What is stored in __defaults__, and why does that explain the mutable default bug? Where does a closure variable live after the outer function returns? Which parameters in def f(a, /, b, *c, d, **e) can be passed by name?
Quiz Bank
FoundationalWhat is the difference between global and nonlocal?
Both change the compiler's decision that an assigned name is local. global x makes x refer to the module-level variable, even inside a nested function. nonlocal x makes x refer to the nearest enclosing function's variable, and it is an error if no enclosing function has one. You need nonlocal to rebind a closure variable, for example to increment a counter kept in the outer function. Neither is needed just to read a variable from an outer scope, because reading follows the normal LEGB search.
AppliedA function has the signature def log_event(name, created_at=datetime.now()). Every event logged in a day has the same timestamp. Why?
The default expression datetime.now() runs once, when the def statement executes, which is when the module is imported. The resulting datetime object is stored in log_event.__defaults__ and reused for every call that does not pass a timestamp. Use created_at=None and set created_at = created_at or datetime.now(timezone.utc) inside the body, so the clock is read on every call.
InterviewWrite a function that returns a function which remembers how many times it has been called. Then explain how the state survives.
python
def make_call_counter():
calls = 0
def counted():
nonlocal calls
calls += 1
return calls
return countedcalls is used by the inner function, so the compiler stores it in a cell instead of a plain local slot. counted carries a pointer to that cell in its __closure__ tuple. When make_call_counter returns, its frame is discarded, but the cell stays alive because counted still references it. Each call reads and writes the cell with LOAD_DEREF and STORE_DEREF. nonlocal is needed because calls += 1 assigns, and without it the compiler would make calls a fresh local.
StaffYou are designing a public library function with eight options. How do you choose which parameters are positional-only, normal and keyword-only, and why does it matter for the library's future?
Make the one or two essential inputs, whose meaning is obvious from position, positional-only or normal. For example, the data being processed. Make every option keyword-only with a bare *, so calls read like export(rows, *, format="csv", compress=True) and boolean flags are never anonymous. This is about future changes. Keyword-only options can be reordered and new ones added anywhere without breaking callers. Positional-only parameters can be renamed freely, because no caller can depend on the name. A signature that allows everything by position freezes both the order and the names forever, because any change breaks someone.
Next: closures plus "functions are objects" give you one of Python's most loved features. 3.13.5 shows what the @ symbol really does, builds every kind of decorator by hand, and opens up the special ones in the standard library.