Zope Deferred Import

Warnings

• breaking Versions 6.x and above of `zope.deferredimport` require Python 3.10 or higher. Projects on older Python versions (e.g., 3.9 or earlier) must use an older version of the library (e.g., 5.x) or upgrade their Python interpreter.
  Fix: Upgrade Python to 3.10+ or pin `zope.deferredimport<6` in your project's dependencies.
• gotcha When a deferred-imported symbol is accessed but its underlying source cannot be found (e.g., the module doesn't exist, or the attribute is missing), the `AttributeError` will be raised at the *point of access*, not necessarily where `deferredImport` was called. This can make debugging unexpected `AttributeError`s tricky as the traceback doesn't immediately point to the source of the deferred definition.
  Fix: Thoroughly test deferred imports. During debugging, inspect `sys.modules` and the target module's `__dict__` to verify that the source modules are correctly loaded and contain the expected symbols.
• gotcha The performance benefits (faster startup time) of `zope.deferredimport` only materialize if the deferred symbols are *not* immediately accessed after the `deferredImport` call. If a symbol is accessed on the next line, the import happens immediately, largely negating the startup improvement for that specific symbol.
  Fix: Ensure that code paths requiring deferred symbols are genuinely lazy. Defer imports only for components that are not always needed during application startup or during module initialization.
• gotcha Modules using `deferredImport` do not automatically populate their `__all__` attribute with the deferred symbols. This means that `from my_module import *` will not expose deferred names without explicit modification of `my_module.__all__`.
  Fix: If `from ... import *` behavior is desired, explicitly define or append the names of the deferred symbols to the `__all__` list in the module where `deferredImport` is used.

Install

• pip install zope.deferredimport Install stable version

Imports

• deferredImport

  from zope.deferredimport import deferredImport

Quickstart

This quickstart demonstrates how to use `deferredImport` to lazily load symbols into a target module. The symbols are only imported from their source module when they are first accessed, helping to reduce initial load times. It also shows how attempts to access non-existent deferred items will correctly raise an `AttributeError`.

import sys
from zope.deferredimport import deferredImport

# Simulate a module that would be slow to import or cause a circular dependency
# In a real scenario, 'my_app.utils' might be a separate file/module.
sys.modules['my_app.utils'] = type('module', (object,), {
    'complex_function': lambda: "Complex function executed!",
    'helper_constant': 42,
    'another_item': 'hello'
})

# Define deferred imports for a target module 'my_app.api'
deferredImport(
    'my_app.api',
    'my_app.utils:complex_function',
    'my_app.utils:helper_constant',
    'my_app.utils:non_existent_item', # This will raise AttributeError on access
)

# At this point, 'my_app.api' exists but its contents are not loaded (lazy)
print(f"Is 'my_app.api' in sys.modules? {'my_app.api' in sys.modules}")
print(f"Has 'complex_function' been imported yet? {'complex_function' in sys.modules.get('my_app.api', {}).__dict__}")

# Accessing 'complex_function' triggers its import from 'my_app.utils'
import my_app.api
print(f"Value of complex_function: {my_app.api.complex_function()}")
print(f"Has 'complex_function' been imported now? {'complex_function' in sys.modules.get('my_app.api', {}).__dict__}")
print(f"Value of helper_constant: {my_app.api.helper_constant}")

# Accessing a non-existent item will raise an AttributeError as expected
try:
    my_app.api.non_existent_item
except AttributeError as e:
    print(f"Expected error for non-existent item: {e}")

# Clean up sys.modules for example isolation (not typically done in app code)
del sys.modules['my_app.utils']
del sys.modules['my_app.api']