Scope decides where a name lives and which name wins when two places use the same word. The LEGB rule is the whole system in four letters, and once you can recite it, the confusing errors stop being mysterious.
The previous lesson in this module covered "Return Values, Multiple Returns and None", and this lesson is the last one in the Python Functions module.
What is scope and why does it exist?
A scope is a region of a program where a name is visible. Every variable that you write belongs to one, and Python uses scope to stop two unrelated pieces of code from colliding over the word count. When you write total = 0 inside a function, that total is a different variable from a total in the file above it, even though they share the same name.
The point is not bureaucracy. The point is that a function should be able to assume that it is the only code running, that its helper variables cannot be corrupted by unrelated code, and that reading a function tells you exactly which values it depends on. Scope is how Python gives you all of that without asking you to declare anything.
Two terms are worth separating here. A namespace is the container itself, such as the module's dictionary, a function's mapping of local names, or the built-in table. A scope is the region of code that can reach a namespace. You rarely need the difference, but it explains why globals() and locals() return dictionaries.
What does the LEGB rule mean?
Every time Python evaluates a name, it looks in four places, in this order, and it stops at the first one that has it.
| Letter | Scope | Where it comes from |
|---|---|---|
| L | Local | Names assigned inside the current function |
| E | Enclosing | Names in the function that called the current one |
| G | Global | Names at the top level of your module |
| B | Built-in | Python's own names, such as print, len, and range |
def demo():
label = 'local name'
print(label)
demo()
print(len('python'))
print(sorted([3, 1, 2]))
The built-in scope is the one that people forget, and it explains a whole class of confusing errors. If you write list = [1, 2, 3] at the top of a module, then you have shadowed the built-in list for that whole file, and any later call to list(...) now fails with TypeError: 'list' object is not callable. Nothing about the built-in changed. Your name simply won the lookup.
The search order also explains a small optimisation that surprises people. Python works out the local names of a function once, when it sees the def, so a name that is assigned anywhere in the body is local for the whole body. That single fact is the cause of the error in the next-but-one section.
Why does Python have no block scope?
An if, a for loop, a while loop, and a try block do not create a scope. Variables that are assigned inside them live in whatever scope encloses the block, and that is usually the module or the function that contains it.
if True:
level = 'set inside an if block'
print(level)
for item in ['a', 'b']:
last = item
print(last, item)
Only a handful of constructs introduce a new scope. Functions, classes, modules, and comprehensions do. That is why a loop variable like item is still there after the loop finishes, and why it can shadow an outer variable of the same name without giving you any warning.
Comprehensions are the exception that people rarely expect, because they look like a loop but behave like a function. The body of a comprehension has its own scope, so the loop variable does not leak out of it.
doubled = [n * 2 for n in range(4)]
print(doubled)
try:
print(n)
except NameError as error:
print('NameError:', error)
That difference between a loop and a comprehension is the reason that comprehension variables do not leak. It also means that a comprehension cannot see the names of the module where it appears, unless you pass them in, which surprises people the first time they try to build a list from a global threshold inside a function.
What causes an UnboundLocalError?
This is the error that teaches LEGB better than any explanation can. Inside a function, a name that is assigned anywhere in the body is local for the whole body. If you read that name before the assignment runs, then Python refuses to fall back to the global one, because the local exists and it simply has no value yet.
count = 0
def report():
try:
print(count)
except UnboundLocalError as error:
print('UnboundLocalError:', error)
count = 5
report()
print('global count is still:', count)
The fix is not to sprinkle global everywhere. The fix is to rename the local variable, or to pass the value in as a parameter. Renaming is almost always the right answer, because a function that changes a global is a function whose behaviour depends on invisible state, and two calls to it can give different answers.
Understanding this rule also explains a subtle bug. A function that reads a global and then assigns to a different variable of the same name is fine, but a function that reads and assigns the same name is not. The compiler does not care about the order of your statements. It cares that the name is assigned in the body.
When do you need the global keyword?
Rarely. global tells Python to bind a name to the module-level namespace instead of creating a local one. It exists for genuine module-level state, such as a configuration flag that a command-line handler flips once at startup.
count = 0
def bump():
global count
count += 1
bump()
bump()
print('after two bumps:', count)
Notice what global does not do. It does not make a global visible inside a function. A global is visible in every scope regardless, because it is further down the LEGB chain. global only changes where an assignment lands.
That distinction explains a split personality that catches everybody eventually.
items = []
def add_mutating(value):
items.append(value) # changes the shared list, no global needed
def add_rebinding(value):
global items
items = items + [value] # replaces the module-level name
add_mutating('a')
add_rebinding('b')
print(items)
Appending to a list works without global because you are changing the object that the name points at. Rebinding replaces the name itself, so without global Python would create a local copy and throw the original away. The same distinction shows up in lesson six, where copying and referencing lists turns out to be the same idea.
How do closures fit into scope?
When a nested function refers to a name from the function that contains it, then that name is enclosing scope, which is the E in LEGB. The inner function carries a reference to the outer function's scope, and that pairing is called a closure.
def make_accumulator():
total = 0
def add(amount):
nonlocal total
total += amount
return total
add(10)
add(5)
return total
print('accumulated:', make_accumulator())
nonlocal is the counterpart to global. It binds the name to the nearest enclosing function scope rather than creating a local one. Without it, total += amount would create a new local total and would raise the same UnboundLocalError that you met in the previous section.
Closures are how you build stateful objects without writing a class, such as a counter, a rate limiter, or a cache that remembers old answers. You will build one properly in the advanced functions module. For now, the important idea is that a nested function can read and, with nonlocal, update the state of the function that created it.
Key takeaways
- Python resolves a name by checking local, then enclosing, then global, then built-in. The first hit wins, and nothing after it is consulted.
- Blocks do not create scopes. Functions, classes, modules, and comprehensions do.
- A name that is assigned anywhere inside a function is local to that whole function, and that is the entire reason
UnboundLocalErrorexists. - Changing a shared object needs no
global, but replacing its name does. Prefer parameters over globals, and rename rather than reaching forglobal. nonlocalreaches one scope outwards, into the function that defined the nested one.
Now try it yourself. Write def make_counter() that returns an inner function which increments and returns a counter, using nonlocal instead of a class. Then write def report() that tries to read a module-level variable and to assign to it in the same body, catch the UnboundLocalError on purpose, and then fix it by renaming. Finally, write a loop that assigns a variable and a comprehension that does the same thing, and use locals() and globals() to print which scope each name ended up in.