7. Names and Namespaces#
7.1. Overview#
This lecture is all about variable names, how they can be used and how they are understood by the Python interpreter.
This might sound a little dull but the model that Python has adopted for handling names is elegant and interesting.
In addition, you will save yourself many hours of debugging if you have a good understanding of how names work in Python.
7.2. Variable Names in Python#
Consider the Python statement
x = 42
We now know that when this statement is executed, Python creates an object of
type int
in your computer’s memory, containing
the value
42
some associated attributes
But what is x
itself?
In Python, x
is called a name, and the statement x = 42
binds the name x
to the integer object we have just discussed.
Under the hood, this process of binding names to objects is implemented as a dictionary—more about this in a moment.
There is no problem binding two or more names to the one object, regardless of what that object is
def f(string): # Create a function called f
print(string) # that prints any string it's passed
g = f
id(g) == id(f)
True
g('test')
test
In the first step, a function object is created, and the name f
is bound to it.
After binding the name g
to the same object, we can use it anywhere we would use f
.
What happens when the number of names bound to an object goes to zero?
Here’s an example of this situation, where the name x
is first bound to one object and then rebound to another
x = 'foo'
id(x)
x = 'bar'
id(x)
140641007083008
In this case, after we rebind x
to 'bar'
, no names bound are to the first object 'foo'
.
This is a trigger for 'foo'
to be garbage collected.
In other words, the memory slot that stores that object is deallocated and returned to the operating system.
Garbage collection is actually an active research area in computer science.
You can read more on garbage collection if you are interested.
7.3. Namespaces#
Recall from the preceding discussion that the statement
x = 42
binds the name x
to the integer object on the right-hand side.
We also mentioned that this process of binding x
to the correct object is implemented as a dictionary.
This dictionary is called a namespace.
Definition
A namespace is a symbol table that maps names to objects in memory.
Python uses multiple namespaces, creating them on the fly as necessary.
For example, every time we import a module, Python creates a namespace for that module.
To see this in action, suppose we write a script mathfoo.py
with a single line
%%file mathfoo.py
pi = 'foobar'
Writing mathfoo.py
Now we start the Python interpreter and import it
import mathfoo
Next let’s import the math
module from the standard library
import math
Both of these modules have an attribute called pi
math.pi
3.141592653589793
mathfoo.pi
'foobar'
These two different bindings of pi
exist in different namespaces, each one implemented as a dictionary.
If you wish, you can look at the dictionary directly, using module_name.__dict__
.
import math
math.__dict__.items()
dict_items([('__name__', 'math'), ('__doc__', 'This module provides access to the mathematical functions\ndefined by the C standard.'), ('__package__', ''), ('__loader__', <_frozen_importlib_external.ExtensionFileLoader object at 0x7fe98aab2870>), ('__spec__', ModuleSpec(name='math', loader=<_frozen_importlib_external.ExtensionFileLoader object at 0x7fe98aab2870>, origin='/home/runner/miniconda3/envs/quantecon/lib/python3.12/lib-dynload/math.cpython-312-x86_64-linux-gnu.so')), ('acos', <built-in function acos>), ('acosh', <built-in function acosh>), ('asin', <built-in function asin>), ('asinh', <built-in function asinh>), ('atan', <built-in function atan>), ('atan2', <built-in function atan2>), ('atanh', <built-in function atanh>), ('cbrt', <built-in function cbrt>), ('ceil', <built-in function ceil>), ('copysign', <built-in function copysign>), ('cos', <built-in function cos>), ('cosh', <built-in function cosh>), ('degrees', <built-in function degrees>), ('dist', <built-in function dist>), ('erf', <built-in function erf>), ('erfc', <built-in function erfc>), ('exp', <built-in function exp>), ('exp2', <built-in function exp2>), ('expm1', <built-in function expm1>), ('fabs', <built-in function fabs>), ('factorial', <built-in function factorial>), ('floor', <built-in function floor>), ('fmod', <built-in function fmod>), ('frexp', <built-in function frexp>), ('fsum', <built-in function fsum>), ('gamma', <built-in function gamma>), ('gcd', <built-in function gcd>), ('hypot', <built-in function hypot>), ('isclose', <built-in function isclose>), ('isfinite', <built-in function isfinite>), ('isinf', <built-in function isinf>), ('isnan', <built-in function isnan>), ('isqrt', <built-in function isqrt>), ('lcm', <built-in function lcm>), ('ldexp', <built-in function ldexp>), ('lgamma', <built-in function lgamma>), ('log', <built-in function log>), ('log1p', <built-in function log1p>), ('log10', <built-in function log10>), ('log2', <built-in function log2>), ('modf', <built-in function modf>), ('pow', <built-in function pow>), ('radians', <built-in function radians>), ('remainder', <built-in function remainder>), ('sin', <built-in function sin>), ('sinh', <built-in function sinh>), ('sqrt', <built-in function sqrt>), ('tan', <built-in function tan>), ('tanh', <built-in function tanh>), ('sumprod', <built-in function sumprod>), ('trunc', <built-in function trunc>), ('prod', <built-in function prod>), ('perm', <built-in function perm>), ('comb', <built-in function comb>), ('nextafter', <built-in function nextafter>), ('ulp', <built-in function ulp>), ('__file__', '/home/runner/miniconda3/envs/quantecon/lib/python3.12/lib-dynload/math.cpython-312-x86_64-linux-gnu.so'), ('pi', 3.141592653589793), ('e', 2.718281828459045), ('tau', 6.283185307179586), ('inf', inf), ('nan', nan)])
import mathfoo
mathfoo.__dict__
{'__name__': 'mathfoo',
'__doc__': None,
'__package__': '',
'__loader__': <_frozen_importlib_external.SourceFileLoader at 0x7fe98ab2d400>,
'__spec__': ModuleSpec(name='mathfoo', loader=<_frozen_importlib_external.SourceFileLoader object at 0x7fe98ab2d400>, origin='/home/runner/work/lecture-python-programming.myst/lecture-python-programming.myst/lectures/mathfoo.py'),
'__file__': '/home/runner/work/lecture-python-programming.myst/lecture-python-programming.myst/lectures/mathfoo.py',
'__cached__': '/home/runner/work/lecture-python-programming.myst/lecture-python-programming.myst/lectures/__pycache__/mathfoo.cpython-312.pyc',
'__builtins__': {'__name__': 'builtins',
'__doc__': "Built-in functions, types, exceptions, and other objects.\n\nThis module provides direct access to all 'built-in'\nidentifiers of Python; for example, builtins.len is\nthe full name for the built-in function len().\n\nThis module is not normally accessed explicitly by most\napplications, but can be useful in modules that provide\nobjects with the same name as a built-in value, but in\nwhich the built-in of that name is also needed.",
'__package__': '',
'__loader__': _frozen_importlib.BuiltinImporter,
'__spec__': ModuleSpec(name='builtins', loader=<class '_frozen_importlib.BuiltinImporter'>, origin='built-in'),
'__build_class__': <function __build_class__>,
'__import__': <function __import__(name, globals=None, locals=None, fromlist=(), level=0)>,
'abs': <function abs(x, /)>,
'all': <function all(iterable, /)>,
'any': <function any(iterable, /)>,
'ascii': <function ascii(obj, /)>,
'bin': <function bin(number, /)>,
'breakpoint': <function breakpoint>,
'callable': <function callable(obj, /)>,
'chr': <function chr(i, /)>,
'compile': <function compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1, *, _feature_version=-1)>,
'delattr': <function delattr(obj, name, /)>,
'dir': <function dir>,
'divmod': <function divmod(x, y, /)>,
'eval': <function eval(source, globals=None, locals=None, /)>,
'exec': <function exec(source, globals=None, locals=None, /, *, closure=None)>,
'format': <function format(value, format_spec='', /)>,
'getattr': <function getattr>,
'globals': <function globals()>,
'hasattr': <function hasattr(obj, name, /)>,
'hash': <function hash(obj, /)>,
'hex': <function hex(number, /)>,
'id': <function id(obj, /)>,
'input': <bound method Kernel.raw_input of <ipykernel.ipkernel.IPythonKernel object at 0x7fe987ea0830>>,
'isinstance': <function isinstance(obj, class_or_tuple, /)>,
'issubclass': <function issubclass(cls, class_or_tuple, /)>,
'iter': <function iter>,
'aiter': <function aiter(async_iterable, /)>,
'len': <function len(obj, /)>,
'locals': <function locals()>,
'max': <function max>,
'min': <function min>,
'next': <function next>,
'anext': <function anext>,
'oct': <function oct(number, /)>,
'ord': <function ord(c, /)>,
'pow': <function pow(base, exp, mod=None)>,
'print': <function print(*args, sep=' ', end='\n', file=None, flush=False)>,
'repr': <function repr(obj, /)>,
'round': <function round(number, ndigits=None)>,
'setattr': <function setattr(obj, name, value, /)>,
'sorted': <function sorted(iterable, /, *, key=None, reverse=False)>,
'sum': <function sum(iterable, /, start=0)>,
'vars': <function vars>,
'None': None,
'Ellipsis': Ellipsis,
'NotImplemented': NotImplemented,
'False': False,
'True': True,
'bool': bool,
'memoryview': memoryview,
'bytearray': bytearray,
'bytes': bytes,
'classmethod': classmethod,
'complex': complex,
'dict': dict,
'enumerate': enumerate,
'filter': filter,
'float': float,
'frozenset': frozenset,
'property': property,
'int': int,
'list': list,
'map': map,
'object': object,
'range': range,
'reversed': reversed,
'set': set,
'slice': slice,
'staticmethod': staticmethod,
'str': str,
'super': super,
'tuple': tuple,
'type': type,
'zip': zip,
'__debug__': True,
'BaseException': BaseException,
'BaseExceptionGroup': BaseExceptionGroup,
'Exception': Exception,
'GeneratorExit': GeneratorExit,
'KeyboardInterrupt': KeyboardInterrupt,
'SystemExit': SystemExit,
'ArithmeticError': ArithmeticError,
'AssertionError': AssertionError,
'AttributeError': AttributeError,
'BufferError': BufferError,
'EOFError': EOFError,
'ImportError': ImportError,
'LookupError': LookupError,
'MemoryError': MemoryError,
'NameError': NameError,
'OSError': OSError,
'ReferenceError': ReferenceError,
'RuntimeError': RuntimeError,
'StopAsyncIteration': StopAsyncIteration,
'StopIteration': StopIteration,
'SyntaxError': SyntaxError,
'SystemError': SystemError,
'TypeError': TypeError,
'ValueError': ValueError,
'Warning': Warning,
'FloatingPointError': FloatingPointError,
'OverflowError': OverflowError,
'ZeroDivisionError': ZeroDivisionError,
'BytesWarning': BytesWarning,
'DeprecationWarning': DeprecationWarning,
'EncodingWarning': EncodingWarning,
'FutureWarning': FutureWarning,
'ImportWarning': ImportWarning,
'PendingDeprecationWarning': PendingDeprecationWarning,
'ResourceWarning': ResourceWarning,
'RuntimeWarning': RuntimeWarning,
'SyntaxWarning': SyntaxWarning,
'UnicodeWarning': UnicodeWarning,
'UserWarning': UserWarning,
'BlockingIOError': BlockingIOError,
'ChildProcessError': ChildProcessError,
'ConnectionError': ConnectionError,
'FileExistsError': FileExistsError,
'FileNotFoundError': FileNotFoundError,
'InterruptedError': InterruptedError,
'IsADirectoryError': IsADirectoryError,
'NotADirectoryError': NotADirectoryError,
'PermissionError': PermissionError,
'ProcessLookupError': ProcessLookupError,
'TimeoutError': TimeoutError,
'IndentationError': IndentationError,
'IndexError': IndexError,
'KeyError': KeyError,
'ModuleNotFoundError': ModuleNotFoundError,
'NotImplementedError': NotImplementedError,
'RecursionError': RecursionError,
'UnboundLocalError': UnboundLocalError,
'UnicodeError': UnicodeError,
'BrokenPipeError': BrokenPipeError,
'ConnectionAbortedError': ConnectionAbortedError,
'ConnectionRefusedError': ConnectionRefusedError,
'ConnectionResetError': ConnectionResetError,
'TabError': TabError,
'UnicodeDecodeError': UnicodeDecodeError,
'UnicodeEncodeError': UnicodeEncodeError,
'UnicodeTranslateError': UnicodeTranslateError,
'ExceptionGroup': ExceptionGroup,
'EnvironmentError': OSError,
'IOError': OSError,
'open': <function _io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)>,
'copyright': Copyright (c) 2001-2023 Python Software Foundation.
All Rights Reserved.
Copyright (c) 2000 BeOpen.com.
All Rights Reserved.
Copyright (c) 1995-2001 Corporation for National Research Initiatives.
All Rights Reserved.
Copyright (c) 1991-1995 Stichting Mathematisch Centrum, Amsterdam.
All Rights Reserved.,
'credits': Thanks to CWI, CNRI, BeOpen.com, Zope Corporation and a cast of thousands
for supporting Python development. See www.python.org for more information.,
'license': Type license() to see the full license text,
'help': Type help() for interactive help, or help(object) for help about object.,
'execfile': <function _pydev_bundle._pydev_execfile.execfile(file, glob=None, loc=None)>,
'runfile': <function _pydev_bundle.pydev_umd.runfile(filename, args=None, wdir=None, namespace=None)>,
'__IPYTHON__': True,
'display': <function IPython.core.display_functions.display(*objs, include=None, exclude=None, metadata=None, transient=None, display_id=None, raw=False, clear=False, **kwargs)>,
'get_ipython': <bound method InteractiveShell.get_ipython of <ipykernel.zmqshell.ZMQInteractiveShell object at 0x7fe987ea1c70>>},
'pi': 'foobar'}
As you know, we access elements of the namespace using the dotted attribute notation
math.pi
3.141592653589793
This is entirely equivalent to math.__dict__['pi']
math.__dict__['pi']
3.141592653589793
7.4. Viewing Namespaces#
As we saw above, the math
namespace can be printed by typing math.__dict__
.
Another way to see its contents is to type vars(math)
vars(math).items()
dict_items([('__name__', 'math'), ('__doc__', 'This module provides access to the mathematical functions\ndefined by the C standard.'), ('__package__', ''), ('__loader__', <_frozen_importlib_external.ExtensionFileLoader object at 0x7fe98aab2870>), ('__spec__', ModuleSpec(name='math', loader=<_frozen_importlib_external.ExtensionFileLoader object at 0x7fe98aab2870>, origin='/home/runner/miniconda3/envs/quantecon/lib/python3.12/lib-dynload/math.cpython-312-x86_64-linux-gnu.so')), ('acos', <built-in function acos>), ('acosh', <built-in function acosh>), ('asin', <built-in function asin>), ('asinh', <built-in function asinh>), ('atan', <built-in function atan>), ('atan2', <built-in function atan2>), ('atanh', <built-in function atanh>), ('cbrt', <built-in function cbrt>), ('ceil', <built-in function ceil>), ('copysign', <built-in function copysign>), ('cos', <built-in function cos>), ('cosh', <built-in function cosh>), ('degrees', <built-in function degrees>), ('dist', <built-in function dist>), ('erf', <built-in function erf>), ('erfc', <built-in function erfc>), ('exp', <built-in function exp>), ('exp2', <built-in function exp2>), ('expm1', <built-in function expm1>), ('fabs', <built-in function fabs>), ('factorial', <built-in function factorial>), ('floor', <built-in function floor>), ('fmod', <built-in function fmod>), ('frexp', <built-in function frexp>), ('fsum', <built-in function fsum>), ('gamma', <built-in function gamma>), ('gcd', <built-in function gcd>), ('hypot', <built-in function hypot>), ('isclose', <built-in function isclose>), ('isfinite', <built-in function isfinite>), ('isinf', <built-in function isinf>), ('isnan', <built-in function isnan>), ('isqrt', <built-in function isqrt>), ('lcm', <built-in function lcm>), ('ldexp', <built-in function ldexp>), ('lgamma', <built-in function lgamma>), ('log', <built-in function log>), ('log1p', <built-in function log1p>), ('log10', <built-in function log10>), ('log2', <built-in function log2>), ('modf', <built-in function modf>), ('pow', <built-in function pow>), ('radians', <built-in function radians>), ('remainder', <built-in function remainder>), ('sin', <built-in function sin>), ('sinh', <built-in function sinh>), ('sqrt', <built-in function sqrt>), ('tan', <built-in function tan>), ('tanh', <built-in function tanh>), ('sumprod', <built-in function sumprod>), ('trunc', <built-in function trunc>), ('prod', <built-in function prod>), ('perm', <built-in function perm>), ('comb', <built-in function comb>), ('nextafter', <built-in function nextafter>), ('ulp', <built-in function ulp>), ('__file__', '/home/runner/miniconda3/envs/quantecon/lib/python3.12/lib-dynload/math.cpython-312-x86_64-linux-gnu.so'), ('pi', 3.141592653589793), ('e', 2.718281828459045), ('tau', 6.283185307179586), ('inf', inf), ('nan', nan)])
If you just want to see the names, you can type
# Show the first 10 names
dir(math)[0:10]
['__doc__',
'__file__',
'__loader__',
'__name__',
'__package__',
'__spec__',
'acos',
'acosh',
'asin',
'asinh']
Notice the special names __doc__
and __name__
.
These are initialized in the namespace when any module is imported
__doc__
is the doc string of the module__name__
is the name of the module
print(math.__doc__)
This module provides access to the mathematical functions
defined by the C standard.
math.__name__
'math'
7.5. Interactive Sessions#
In Python, all code executed by the interpreter runs in some module.
What about commands typed at the prompt?
These are also regarded as being executed within a module — in this case, a module called __main__
.
To check this, we can look at the current module name via the value of __name__
given at the prompt
print(__name__)
__main__
When we run a script using IPython’s run
command, the contents of the file are executed as part of __main__
too.
To see this, let’s create a file mod.py
that prints its own __name__
attribute
%%file mod.py
print(__name__)
Writing mod.py
Now let’s look at two different ways of running it in IPython
import mod # Standard import
mod
%run mod.py # Run interactively
__main__
In the second case, the code is executed as part of __main__
, so __name__
is equal to __main__
.
To see the contents of the namespace of __main__
we use vars()
rather than vars(__main__)
.
If you do this in IPython, you will see a whole lot of variables that IPython needs, and has initialized when you started up your session.
If you prefer to see only the variables you have initialized, use %whos
x = 2
y = 3
import numpy as np
%whos
Variable Type Data/Info
--------------------------------
f function <function f at 0x7fe987cef380>
g function <function f at 0x7fe987cef380>
math module <module 'math' from '/hom<...>312-x86_64-linux-gnu.so'>
mathfoo module <module 'mathfoo' from '/<...>yst/lectures/mathfoo.py'>
mod module <module 'mod' from '/home<...>ng.myst/lectures/mod.py'>
np module <module 'numpy' from '/ho<...>kages/numpy/__init__.py'>
x int 2
y int 3
7.6. The Global Namespace#
Python documentation often makes reference to the “global namespace”.
The global namespace is the namespace of the module currently being executed.
For example, suppose that we start the interpreter and begin making assignments.
We are now working in the module __main__
, and hence the namespace for __main__
is the global namespace.
Next, we import a module called amodule
import amodule
At this point, the interpreter creates a namespace for the module amodule
and starts executing commands in the module.
While this occurs, the namespace amodule.__dict__
is the global namespace.
Once execution of the module finishes, the interpreter returns to the module from where the import statement was made.
In this case it’s __main__
, so the namespace of __main__
again becomes the global namespace.
7.7. Local Namespaces#
Important fact: When we call a function, the interpreter creates a local namespace for that function, and registers the variables in that namespace.
The reason for this will be explained in just a moment.
Variables in the local namespace are called local variables.
After the function returns, the namespace is deallocated and lost.
While the function is executing, we can view the contents of the local namespace with locals()
.
For example, consider
def f(x):
a = 2
print(locals())
return a * x
Now let’s call the function
f(1)
{'x': 1, 'a': 2}
2
You can see the local namespace of f
before it is destroyed.
7.8. The __builtins__
Namespace#
We have been using various built-in functions, such as max(), dir(), str(), list(), len(), range(), type()
, etc.
How does access to these names work?
These definitions are stored in a module called
__builtin__
.They have their own namespace called
__builtins__
.
# Show the first 10 names in `__main__`
dir()[0:10]
['In', 'Out', '_', '_10', '_11', '_12', '_13', '_14', '_15', '_16']
# Show the first 10 names in `__builtins__`
dir(__builtins__)[0:10]
['ArithmeticError',
'AssertionError',
'AttributeError',
'BaseException',
'BaseExceptionGroup',
'BlockingIOError',
'BrokenPipeError',
'BufferError',
'BytesWarning',
'ChildProcessError']
We can access elements of the namespace as follows
__builtins__.max
<function max>
But __builtins__
is special, because we can always access them directly as well
max
<function max>
__builtins__.max == max
True
The next section explains how this works …
7.9. Name Resolution#
Namespaces are great because they help us organize variable names.
(Type import this
at the prompt and look at the last item that’s printed)
However, we do need to understand how the Python interpreter works with multiple namespaces.
Understanding the flow of execution will help us to check which variables are in scope and how to operate on them when writing and debugging programs.
At any point of execution, there are in fact at least two namespaces that can be accessed directly.
(“Accessed directly” means without using a dot, as in pi
rather than math.pi
)
These namespaces are
The global namespace (of the module being executed)
The builtin namespace
If the interpreter is executing a function, then the directly accessible namespaces are
The local namespace of the function
The global namespace (of the module being executed)
The builtin namespace
Sometimes functions are defined within other functions, like so
def f():
a = 2
def g():
b = 4
print(a * b)
g()
Here f
is the enclosing function for g
, and each function gets its
own namespaces.
Now we can give the rule for how namespace resolution works:
The order in which the interpreter searches for names is
the local namespace (if it exists)
the hierarchy of enclosing namespaces (if they exist)
the global namespace
the builtin namespace
If the name is not in any of these namespaces, the interpreter raises a NameError
.
This is called the LEGB rule (local, enclosing, global, builtin).
Here’s an example that helps to illustrate.
Visualizations here are created by nbtutor in a Jupyter notebook.
They can help you better understand your program when you are learning a new language.
Consider a script test.py
that looks as follows
%%file test.py
def g(x):
a = 1
x = x + a
return x
a = 0
y = g(10)
print("a = ", a, "y = ", y)
Writing test.py
What happens when we run this script?
%run test.py
a = 0 y = 11
First,
The global namespace
{}
is created.
The function object is created, and
g
is bound to it within the global namespace.The name
a
is bound to0
, again in the global namespace.
Next g
is called via y = g(10)
, leading to the following sequence of actions
The local namespace for the function is created.
Local names
x
anda
are bound, so that the local namespace becomes{'x': 10, 'a': 1}
.
Note that the global a
was not affected by the local a
.
Statement
x = x + a
uses the locala
and localx
to computex + a
, and binds local namex
to the result.This value is returned, and
y
is bound to it in the global namespace.Local
x
anda
are discarded (and the local namespace is deallocated).
7.9.1. Mutable Versus Immutable Parameters#
This is a good time to say a little more about mutable vs immutable objects.
Consider the code segment
def f(x):
x = x + 1
return x
x = 1
print(f(x), x)
2 1
We now understand what will happen here: The code prints 2
as the value of f(x)
and 1
as the value of x
.
First f
and x
are registered in the global namespace.
The call f(x)
creates a local namespace and adds x
to it, bound to 1
.
Next, this local x
is rebound to the new integer object 2
, and this value is returned.
None of this affects the global x
.
However, it’s a different story when we use a mutable data type such as a list
def f(x):
x[0] = x[0] + 1
return x
x = [1]
print(f(x), x)
[2] [2]
This prints [2]
as the value of f(x)
and same for x
.
Here’s what happens
f
is registered as a function in the global namespace
x
is bound to[1]
in the global namespace
The call
f(x)
Creates a local namespace
Adds
x
to the local namespace, bound to[1]
Note
The global x
and the local x
refer to the same [1]
We can see the identity of local x
and the identity of global x
are the same
def f(x):
x[0] = x[0] + 1
print(f'the identity of local x is {id(x)}')
return x
x = [1]
print(f'the identity of global x is {id(x)}')
print(f(x), x)
the identity of global x is 140640801193664
the identity of local x is 140640801193664
[2] [2]
Within
f(x)
The list
[1]
is modified to[2]
Returns the list
[2]
The local namespace is deallocated, and the local
x
is lost
If you want to modify the local x
and the global x
separately, you can create a copy of the list and assign the copy to the local x
.
We will leave this for you to explore.