Names and Namespaces

5. Names and Namespaces#

5.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.

5.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)

2077750336304

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.

5.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'

Overwriting 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__', <class '_frozen_importlib.BuiltinImporter'>), ('__spec__', ModuleSpec(name='math', loader=<class '_frozen_importlib.BuiltinImporter'>, origin='built-in')), ('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>), ('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 0x1e3c66e9eb0>,
 '__spec__': ModuleSpec(name='mathfoo', loader=<_frozen_importlib_external.SourceFileLoader object at 0x000001E3C66E9EB0>, origin='H:\\discoD\\Programacion\\Python\\pythonbook\\jpbooks\\libro_python\\book\\docs\\mathfoo.py'),
 '__file__': 'H:\\discoD\\Programacion\\Python\\pythonbook\\jpbooks\\libro_python\\book\\docs\\mathfoo.py',
 '__cached__': 'H:\\discoD\\Programacion\\Python\\pythonbook\\jpbooks\\libro_python\\book\\docs\\__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 0x000001E3C4EF2900>>,
  '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,
  'WindowsError': 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 0x000001E3C668B590>>},
 '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

5.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__', <class '_frozen_importlib.BuiltinImporter'>), ('__spec__', ModuleSpec(name='math', loader=<class '_frozen_importlib.BuiltinImporter'>, origin='built-in')), ('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>), ('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__',
 '__loader__',
 '__name__',
 '__package__',
 '__spec__',
 'acos',
 'acosh',
 'asin',
 'asinh',
 'atan']

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'

5.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__)

Overwriting 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 0x000001E3C66AEE80>
g          function    <function f at 0x000001E3C66AEE80>
math       module      <module 'math' (built-in)>
mathfoo    module      <module 'mathfoo' from 'H<...>\book\\docs\\mathfoo.py'>
mod        module      <module 'mod' from 'H:\\d<...>hon\\book\\docs\\mod.py'>
np         module      <module 'numpy' from 'C:\<...>ges\\numpy\\__init__.py'>
x          int         2
y          int         3

5.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.

5.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.

5.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 …

5.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

  1. the local namespace (if it exists)

  2. the hierarchy of enclosing namespaces (if they exist)

  3. the global namespace

  4. 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)

Overwriting 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 to 0, 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 and a 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 local a and local x to compute x + a, and binds local name x to the result.

  • This value is returned, and y is bound to it in the global namespace.

  • Local x and a are discarded (and the local namespace is deallocated).

5.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 2078034786624
the identity of local x is 2078034786624
[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.

Contents