Python Module Attribute Access

Advanced

Python modules normally expose names stored in their module namespace. The data model also allows a module to customize missing attribute lookup and the names reported by dir(). This lesson is about those module-level hooks, not the instance-level attribute hooks taught in Custom Attribute Access.

Use module __getattr__ as a fallback

A module can define a function named __getattr__ at its top level. When normal module attribute lookup cannot find a name, Python calls that function with the missing attribute name. Return a computed value, or raise AttributeError if the name is genuinely unsupported. In real modules, the function is defined directly in the module source.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import sys

def __getattr__(name):
    if name == "region":
        return "eu-west"
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

module = sys.modules[__name__]
print(module.region)
try:
    print(module.unknown)
except AttributeError as error:
    print(type(error).__name__)

import sys
def __getattr__(name):
    if name == "mode": return "safe"
    raise AttributeError(name)
print(sys.modules[__name__].mode)?

Normal attributes are found first

Module __getattr__ is a fallback, not an interceptor for every attribute. Existing module attributes are returned through normal lookup, so the hook runs only for names that are missing. This differs from instance __getattribute__, which participates in every ordinary instance attribute read.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import sys
calls = []
value = 7

def __getattr__(name):
    calls.append(name)
    if name == "computed":
        return 42
    raise AttributeError(name)

module = sys.modules[__name__]
print(module.value)
print(module.computed)
print(calls)

import sys
calls = []
ready = True
def __getattr__(name):
    calls.append(name)
    return 9
module = sys.modules[__name__]
print(module.ready, calls)
print(module.other, calls)?

Load an attribute lazily and cache it

One practical use is to defer an import until a public module attribute is first requested. If the cost is worth it, save the resolved value in globals() so later lookups use the regular module dictionary. Lazy loading should be intentional: it can make import timing and error timing less obvious.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import importlib
import sys

def __getattr__(name):
    if name == "sqrt":
        value = importlib.import_module("math").sqrt
        globals()[name] = value
        return value
    raise AttributeError(name)

module = sys.modules[__name__]
print(module.sqrt(81))
print("sqrt" in globals())

Customize dir() with __dir__

A module-level __dir__ function takes no arguments and returns an iterable of names that should be exposed by dir(module). Python sorts the returned names. This can make dynamically provided public attributes discoverable, but the returned list should describe a useful interface rather than every internal detail.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import sys
public_value = "ready"

def __getattr__(name):
    if name == "computed":
        return 12
    raise AttributeError(name)

def __dir__():
    return ["public_value", "computed"]

module = sys.modules[__name__]
print(module.computed)
print(dir(module))

import sys
def __dir__():
    return ["virtual", "public"]
print(dir(sys.modules[__name__]))?

Module attribute access is not global-name lookup

A module-level __getattr__ affects attribute-based access such as module.answer and getattr(module, "answer"). It does not create a real entry in the module dictionary or change direct global-name resolution inside the module. Check globals() or module.__dict__ when you need to know what is actually stored.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

import sys

def __getattr__(name):
    if name == "answer":
        return 42
    raise AttributeError(name)

module = sys.modules[__name__]
print(module.answer)
print("answer" in module.__dict__)
print(getattr(module, "answer"))

import sys
def __getattr__(name):
    if name == "answer": return 42
    raise AttributeError(name)
module = sys.modules[__name__]
print(module.answer, "answer" in module.__dict__)?

Handle compatibility names carefully

A module can use __getattr__ to preserve an old public name while warning callers to use a replacement, or to defer loading an expensive dependency. These techniques should remain narrow and documented: return only supported names, raise AttributeError for unknown names, and avoid concealing genuine programming mistakes.

import sys
def __getattr__(name):
    raise AttributeError(name)
print(hasattr(sys.modules[__name__], "not_available"))?