Lesson 12 · Collections and functions

Scope

Where can a name be used? Python keeps names in namespaces: one global namespace for the whole file, and a fresh local namespace every time a function is called. Step through a seven-line program, scope.py, and watch a function read a global name, make its own local one, hand a value back with return, and then forget its local names, so asking for one afterwards stops the program with a NameError.

12 min10 steps5 questionsBeginner

Fig 12 · Interactive

Loading figure…

or ← →

Check yourself

5 quick questions

Pick an answer to see why. Your score saves with your progress.

01x = 1 at the top of a file, and a function f() contains only print(x). What does f() print?

f() never assigns x, so x is not local. Python looks in the local namespace, finds nothing, then looks in the global one and finds 1.

02def g(): y = 5 (and nothing else). After calling g(), what does print(y) at the top level do?

y is local to g(). Its local namespace is forgotten when g() returns, and there is no global y, so Python raises a NameError.

03count = 10 at the top level. A function runs count = 1 and returns. What is the global count now?

Assigning inside the function makes a new local count. The global count is never touched, so it is still 10.

04In which order does Python look a name up?

Innermost first: the local scope, then any enclosing functions, then the module's global names, then the built-in names such as print and len (LEGB). The first match wins.

05Which line inside a function lets it change the module's variable total?

global total tells Python that total in this function means the module's name. Without it, assigning total would make a new local name. Often, returning the new value is the clearer choice.

Key terms

Glossary

Scope: The part of a program where a name can be used directly. A local name's scope is the function it is made in.
Namespace: A mapping from names to values. Python keeps one per module (global), one per function call (local) and one for the built-ins.
Global name: A name assigned at the top level of a file, outside any function. Every function in the file can read it.
Local name: A name assigned inside a function, including its parameters. It exists only while that call runs.
LEGB: The order Python searches for a name: Local, Enclosing functions, Global (the module), Built-in.
global statement: global x inside a function makes x refer to the module's x, so assigning it changes the global name.
NameError: The error Python raises when it cannot find a name in any scope it searches.
UnboundLocalError: The error Python raises when a function uses a local name before assigning it, for example count = count + 1 without global count.

Fine print

Notes and sources

Python looks a name up in up to four scopes, innermost first: the local one, the enclosing functions (when a def sits inside another def), the global one (the module) and the built-in names such as print and len. People remember the order as LEGB.
The Python tutorial says the local namespace is created when the function is called and deleted (better: forgotten) when it returns or raises an exception it does not handle. Each call gets its own fresh one.
Whether a name is local is decided for the whole function before it runs: if the function assigns to the name anywhere (with =, +=, for, import, def and so on), every use of it in that function is local. Reading it before the assignment raises UnboundLocalError.
global count tells Python that count in this function means the module's count; nonlocal does the same for a name in an enclosing function. Use them sparingly: returning a value, as add() does, is usually clearer.
The real traceback also prints the full path of the file, a caret line under the name in newer versions, and the line's code; the figure shortens it.

Quiz Unlocks after the last step.