Python: Scope and Namespaces

What is a Namespace?

A namespace is a mapping from names to objects. Think of it as a dictionary where the keys are variable names (strings) and the values are the actual Python objects those names point to. Python uses namespaces to keep names in different contexts separate: a variable called total inside one function has nothing to do with a variable called total in another function, because they live in different namespaces.

Python maintains several namespaces at any point during execution. A scope is the region of code where a particular namespace is directly visible without any qualification. The two concepts are closely related but distinct: the namespace is the data structure, and the scope is the textual region of code that has access to it.

The LEGB Rule: How Python Resolves Names

Whenever Python encounters a name, it looks it up in a fixed sequence of scopes. The order is Local, then Enclosing, then Global, then Built-in. This is called the LEGB rule. The search stops as soon as Python finds the name in one of these scopes. If the name is not found in any of them, Python raises aNameError.

Knowing this order explains a common source of confusion. If you define a local variable with the same name as a global or built-in, the local one takes precedence inside that function. The global or built-in is still there; it is just shadowed.

The global Keyword

Reading a global variable from inside a function works without any declaration. But the moment Python sees an assignment to a name inside a function, it treats that name as local for the entire function, even lines above the assignment. This causes an UnboundLocalError if you try to read the name before the assignment.

The global statement tells Python that a given name, regardless of assignment, refers to the module-level global and not a new local variable. Use it sparingly. Relying heavily on mutable global state makes code hard to test and reason about. Functions that communicate through arguments and return values are almost always the better design.

The nonlocal Keyword

nonlocal solves the same problem as global but for the enclosing function scope rather than the module scope. Without it, an inner function can read from the enclosing scope but cannot assign to its variables. Declaring a name as nonlocal tells Python to look for it in the nearest enclosing scope that is not global and treat any assignment as a modification of that existing binding.

This is the mechanism that makes stateful closures work. Counters, accumulators, and memoisation caches in closures almost always rely on nonlocal to update their captured state.

__builtins__

The built-in scope is implemented as a module called builtins. Python makes it accessible in every module via the name __builtins__. In the main script,__builtins__ is the module object itself. In imported modules, it is typically the module's __dict__. This inconsistency is a CPython implementation detail, so you should import builtins explicitly if you need reliable access to it.

The most practical use of this knowledge is recovering a shadowed built-in. If you or a library have accidentally overwritten list, open, or another built-in, you can retrieve the original from builtins.

vars(), dir(), locals(), and globals()

Python gives you several built-in tools to inspect namespaces at runtime. Each one answers a slightly different question, and picking the right one avoids confusion.

Module Namespaces

Every module in Python is its own namespace. When you write import math, Python creates a module object and assigns it to the name math in your current namespace. All of math's functions, constants, and classes live inside that module's namespace, accessible as math.sqrt, math.pi, and so on. They never pollute your module's namespace.

When you use from math import sqrt, Python copies the name sqrtinto your current namespace. The module object still exists, but you have no reference to it unless you also do import math. This is whyfrom module import * is discouraged: it dumps all of the module's public names into your namespace, which can cause silent collisions and makes it hard to tell where a name came from.

Name Mangling (__name)

Python does not have truly private attributes. By convention, a single leading underscore (_name) signals that something is intended for internal use and should not be part of the public API. Tools and IDEs respect this convention, but Python does not enforce it.

A double leading underscore (__name) triggers a feature called name mangling. Python rewrites the attribute name by prepending the class name: __balance in class Account becomes_Account__balance. This is not access control; the attribute is still reachable. The purpose is to prevent accidental name collisions when subclasses add attributes with the same name, not to enforce privacy.

Putting It All Together

The example below walks through all four LEGB scopes in a single piece of code and uses global, nonlocal, and the introspection functions in a way that shows how they relate. Reading through it step by step and predicting each output before running it is one of the most effective exercises for making scope truly intuitive.

Quiz - Test Your Knowledge

Ten questions covering namespaces, the LEGB lookup order, the behaviour ofglobal and nonlocal, introspection functions, module namespaces, and name mangling. Several questions test the difference between what Python allows and what it does by default.