Registry / serialization / zope-deferredimport

zope-deferredimport

JSON →
library6.1.1pypypiunverified

zope.deferredimport allows you to perform imports of names that will only be resolved when used in the code. This utility library helps improve application startup time and manage potential circular dependencies by making imports lazy. The current version is 6.1.1, and it receives updates as part of the broader Zope Foundation ecosystem.

pip install zope.deferredimport
INSTALL
IMPORT
SIG · ZOPE-DEFERREDIMPOR
Z
zope-deferredimport
serializationpythonv6.1.1
Install
2.0s avg
Import
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v6.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.1MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.0s · import 0.000s · 21MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

deferredImport
from zope.deferredimport import deferredImport
from zope.deferredimport import deferredImport

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']
Debug
Known issues
breakingVersions 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.
affects: 6.0.0+
gotchaWhen 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.
affects: All versions
gotchaThe 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.
affects: All versions
gotchaModules 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.
affects: All versions
Upgrade
Version history
6.1.1latest on PyPI · released Feb 16, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
42 hits · last 30 days
node
34
OpenAI (training)
1
Resources
zope-deferredimport — pip install zope-deferredimport · libregistry