The Built-in Namespace

Thebuilt-in namespace contains the names of all of Python’s built-in objects. This namespace is available while the Pythoninterpreter is running. So, you can access the names that live in this namespace at any time in your code without explicitly importing them.

You can list the objects in the built-in namespace with thedir() function using the__builtins__ object as an argument:

>>>dir(__builtins__)[    'ArithmeticError',    'AssertionError',    'AttributeError',    'BaseException',    ...    'super',    'tuple',    'type',    'vars',    'zip']

You may recognize some objects here, such asbuilt-in exceptions,built-in functions, andbuilt-in data types. Python creates the built-in namespace when it starts and keeps it active until the interpreter terminates.

The Global Namespace

Theglobal namespace contains the names defined at the module level. Python creates a main global namespace when the main program’s body starts. This namespace remains in existence until the interpreter terminates.

Additionally, each module has its own global namespace. The interpreter creates a global namespace for any module that your program loads with theimport statement. For further reading on main functions and modules in Python, see the following resources:

• Defining Main Functions in Python
• Python Modules and Packages—An Introduction

For now, when you see the termglobal namespace, you can think of it as the one belonging to the main program.

To illustrate, get back to yourREPL session and run the following code:

>>>number=42>>>dir()[    '__annotations__',    '__builtins__',    '__cached__',    '__doc__',    '__file__',    ...    'number']

In this code snippet, you define thenumber variable as a global name. Then, you call the built-indir() function to check the list of names defined in your current global scope. At the end of the list, you’ll find the'number' key, which corresponds to your global variable.

The Local Namespace

The Python interpreter creates a new and dedicated namespace whenever you call a function. This namespace is local to the function and exists only until the function returns:

>>>defdouble_number(number):...result=number*2...print(dir())...returnresult...>>>double_number(4)['number', 'result']8>>>resultTraceback (most recent call last):...NameError:name 'result' is not defined>>>numberTraceback (most recent call last):...NameError:name 'number' is not defined

In this example, thenumber argument and theresult variable are local todouble_number(). Note that if you try to access them after the function has returned, you getNameError exceptions.

The Enclosing or Nonlocal Namespace

You can also define one function inside another. In this case, you’d have what’s known as aninner function. In the example below, you have the three scopes:

 5>>>global_variable="global" 6 7>>>defouter_func(): 8...# Nonlocal scope 9...nonlocal_variable="nonlocal"10...definner_func():11...# Local scope12...local_variable="local"13...print(f"Hi from the '{local_variable}' scope!")14...print(f"Hi from the '{nonlocal_variable}' scope!")15...print(f"Hi from the '{global_variable}' scope!")16...inner_func()17...1819>>>outer_func()20Hi from the 'local' scope!21Hi from the 'nonlocal' scope!22Hi from the 'global' scope!

In this example, you first create a global variable at the module level. Then, you define a function calledouter_func(). Inside this function, you havenonlocal_variable, which is local toouter_func() but nonlocal toinner_func(). Ininner_func(), you create another variable calledlocal_variable, which is local to the function itself.

Each of these namespaces remains in existence until its respective function returns. Python might not immediately reclaim the memory allocated for those namespaces when their functions terminate, but all references to the objects they contain become invalid.

The LEGB Rule for Searching Names

Returning to the question from the previous section, say that you’re referencingx from inside an inner function. In this situation, Python looks forx in the following order:

1. Local: Python searches forx inside the inner function. If it doesn’t findx there, then it moves to the enclosing scope.
2. Enclosing: Next, Python searches forx in the enclosing function’s scope. If it’s not found there, then it moves to the global scope.
3. Global: Python searches forx in the global scope. If it still doesn’t find it, it moves to the built-in scope.
4. Built-in: Finally, Python searches forx in the built-in scope. If it doesn’t findx there, then it raises aNameError exception.

This is what’s known as theLEGB rule. The interpreter searches for a name from the inside out, looking in thelocal,enclosing,global, and finally, thebuilt-in scope:

If Python doesn’t find the name in any of these namespaces, then it raises aNameError exception, as you’ve already learned. In the following sections, you’ll explore some examples that demonstrate how the LEGB rule works in practice.

The LEGB Rule in Action

In the example below, you define thex variable outside bothouter() andinner() so it resides in your current global scope:

>>>x="global">>>defouter():...definner():...print(x)...inner()...>>>outer()global

The call toprint() can only refer to one possiblex. It displays thex object defined in the global namespace, which holds the string"global".

In the next example, you definex in two places: once in the global scope and once inside theouter() function:

>>>x="global">>>defouter():...x="enclosing"...definner():...print(x)...inner()...>>>outer()enclosing

As in the previous example,inner() refers tox, but this time, it has two definitions to choose from:

1. x in the global scope
2. x in the enclosing scope

According to the LEGB rule, the interpreter finds the value from the enclosing scope before looking in the global scope. Soprint() displaysenclosing instead ofglobal.

Next, you definex everywhere. The first definition is in the global scope. The second is insideouter() but outsideinner(). The third one is inside theinner() function:

>>>x="global">>>defouter():...x="enclosing"...definner():...x="local"...print(x)...inner()...>>>outer()local

Now,print() has to distinguish between three different possibilities:

• Thex in the global scope
• Thex in the enclosing scope
• Thex in the scope that’s local toinner()

In this case, the LEGB rule dictates thatinner() first sees its own locally defined value ofx, so theprint() function displayslocal.

Next, you have a situation whereinner() tries to print the value ofx, butx isn’t defined anywhere. This results in an error:

>>>defouter():...definner():...print(x)...inner()...>>>outer()Traceback (most recent call last):...NameError:name 'x' is not defined

This time, Python doesn’t findx in any of the namespaces, so theprint() function generates aNameError exception.

Theglobals() Function

The built-inglobals() function returns a reference to the current global namespace dictionary. You can use it to access the objects in the global namespace. Here’s what it looks like when you start a REPL session:

>>>type(globals())<class 'dict'>>>>globals(){    '__name__': '__main__',    '__doc__': None,    '__package__': '_pyrepl',    ...}

As you can see, the Python interpreter automatically adds several entries inglobals(). Depending on your Python version and operating system, this may look a little different in your environment, but it should be similar.

Now, see what happens when you define a variable in the global scope:

>>>number=42>>>globals(){    '__name__': '__main__',    '__doc__': None,    ...    'number': 42}

After the assignment statementnumber = 42, a new item appears in the global namespace dictionary. The dictionary key is the object’s name,number, and the dictionary value is the object’s value,42.

You would typically access this object in the usual way by referring to its symbolic name,number. But you can also access it indirectly through the global namespace dictionary:

>>>number42>>>globals()["number"]42>>>numberisglobals()["number"]True

You can access the value ofnumber using the dictionary key lookup syntax. Theis operator in the final example confirms that these are the same object.

You can also useglobals() to create and modify entries in the global namespace:

>>>globals()["message"]="Welcome to Real Python!">>>globals(){    '__name__': '__main__',    '__doc__': None,    ...    'number': 42,    'message': 'Welcome to Real Python!'}>>>message'Welcome to Real Python!'>>>globals()["message"]="Hello, World!">>>message'Hello, World!'

In this example, you first create a new global variable calledmessage and assign a string to it. Then, you callglobals() to inspect the namespace and find the new variable at the final position in the dictionary.

Thelocals() Function

Python also provides a built-in function calledlocals(). It’s similar toglobals(), but it lets you access objects in the local namespace instead:

>>>deffunc(x,y):...message="Hello!"...print(locals())...>>>func(10,0.5){'x': 10, 'y': 0.5, 'message': 'Hello!'}

When called withinfunc(),locals() returns a dictionary representing the function’s local namespace. Notice that, in addition to the locally defined variables, the local namespace includes the function argumentsx andy since these are also local tofunc().

When you calllocals() outside a function in the main program, it behaves the same asglobals(), returning a reference to the global namespace:

>>>locals(){    '__name__': '__main__',    '__doc__': None,    '__package__': '_pyrepl',    ...    'func': <function func at 0x104c87c40>}>>>globals(){    '__name__': '__main__',    '__doc__': None,    '__package__': '_pyrepl',    ...    'func': <function func at 0x104c87c40>}>>>locals()isglobals()True

When you calllocals() in the global namespace, you get a reference to the corresponding dictionary. In practice,locals() behaves the same asglobals() in this context.

The Difference Betweenglobals() andlocals()

There’s one slight difference betweenglobals() andlocals() that’s useful to know about. Theglobals() function returns areference to the dictionary that contains the global namespace. Because of this, if you callglobals() and save its return value, then you can add new variables and modify existing ones as you’ve already learned.

In contrast,locals() returns a dictionary that’s acopy of the dictionary that holds the current local namespace rather than a reference to it. Because of this subtle difference, additions to the return value oflocals() won’t modify the actual namespace:

>>>deffunc():...message="Hello!"...loc=locals()...print(f"{loc= }")...number=42...print(f"{loc= }")...loc["message"]="Welcome!"...print(f"{loc= }")...print(f"{locals()= }")...>>>func()loc = {'message': 'Hello!'}loc = {'message': 'Hello!'}loc = {'message': 'Welcome!'}locals() = {'message': 'Hello!', 'loc': {'message': 'Welcome!'}, 'number': 42}

In this example,loc points to the return value oflocals(), which is a copy of the local namespace dictionary.

The assignmentnumber = 42 adds a new variable to the local namespace butnot to the copy thatloc points to. Similarly, the assignmentloc["message"] = 'Welcome!' modifies the value for key"message" inloc, but doesn’t affect the local namespace.

Finally, it’s worth noting thatlocals() returns a shallow copy of the namespace, so any name that points to a mutable object lets you change that object in place. This change is reflected in the local namespace:

>>>deffunc():...fruits=["apple","banana"]...loc=locals()...loc["fruits"].append("orange")...print(f"{loc= }")...print(f"{locals()= }")...>>>func()loc = {    'fruits': ['apple', 'banana', 'orange']}locals() = {    'fruits': ['apple', 'banana', 'orange'],    'loc': {'fruits': ['apple', 'banana', 'orange']}}

In this example, you keep a reference to thelocals() return value inloc. Then, you use this variable to append a new value to thefruits list, which is mutable. This change affects the content of your local namespace, as you can see in the last highlighted line.

Theglobal Statement

What if you need to modify a value in the global scope from within a function? You can do this using the Pythonglobal statement:

>>>x=20>>>deff():...globalx...x=40...print(x)...>>>f()40>>>x40

Theglobal x statement indicates that whilef() executes, references to the namex will refer to thex defined in the global namespace. That means the assignmentx = 40 doesn’t create a new local variable. It assigns a new value tox in the global scope instead:

As you’ve already learned in previous sections,globals() returns a reference to the global namespace dictionary. If you want, you can produce the same result usingglobals() instead of theglobal statement:

>>>x=20>>>deff():...globals()["x"]=40...print(x)...>>>f()40>>>x40

In this example, you directly modify the value of the globalx using theglobals() function and a dictionary key assignment. There isn’t a good reason to do it this way sinceglobal makes the code cleaner and more readable.

If the name specified in theglobal statement doesn’t exist in the global scope when the function starts, then a combination of theglobal statement and an assignment creates it:

>>>yTraceback (most recent call last):...NameError:name 'y' is not defined>>>deff():...globaly...y=20...>>>f()>>>y20

In this case, when you callf(), there’s no object namedy in the global scope. Theglobal y statement declaresy as global, and the assignment in the next line creates the variable in the global namespace for you. However, this is an unusual a way to create global variables and it’s not a recommended practice.

You can also specify several comma-separated names in a singleglobal statement:

>>>x,y,z=10,20,30>>>deff():...globalx,y,z...

Here,x,y, andz are all declared to refer to objects in the global scope by the singleglobal statement on the highlighted line.

A name specified in aglobal statement can’t appear in the function body before theglobal statement:

>>>deff():...print(x)...globalx...  File"<python-input-0>", line3globalx^^^^^^^^SyntaxError:name 'x' is used prior to global declaration

In this example, theglobal statement makesx refer to an object in the global scope. The call toprint() refers tox before theglobal statement, which raises aSyntaxError exception.

Thenonlocal Statement

A similar situation occurs with nested functions when you need to modify variables in the enclosing scope. Thenonlocal keyword addresses this by referring to variables in the nearest enclosing scope, which allows you to modify them within the nested function:

>>>deff():...x=20...defg():...nonlocalx...x=40...g()...print(x)...>>>f()40

After thenonlocal x statement, wheng() accessesx, it refers to thex in the nearest enclosing scope, defined in the outerf() function:

The call toprint() at the end off() confirms thatg() has changed the value ofx in the enclosing scope to40.

It’s important to note that thenonlocal keyword is only applicable in nested functions. You can only use it to access variables in the enclosing scope.