lazy-loader

To make subpackages visible to users without incurring import costs, use lazy.attach in your package's __init__.py. This sets up __getattr__ and __dir__ so that subpackages are only loaded when accessed.

subpackages = [
    ...,
    'filters',
    ...
]

import lazy_loader as lazy
__getattr__, __dir__, _ = lazy.attach(__name__, subpackages)

Install lazy-loader using pip. It is recommended to use Python >= 3.11. To avoid a known race condition, use Python 3.11.9+ or 3.12.3+.

pip install -U lazy-loader

When a function has the same name as a submodule it resides in (e.g., a max_tree function in max_tree.py), the Python import machinery can accidentally overwrite the function attribute with the submodule attribute during import.

lazy_loader handles this using a _ShadowGuardModule class. This mechanism tracks protected names in a __lazy_shadowed__ attribute and suppresses dictionary updates that would cause a function to be shadowed by its parent module.

To catch missing imports immediately during development or testing (rather than waiting for attribute access), set the EAGER_IMPORT environment variable:

• EAGER_IMPORT=1 or EAGER_IMPORT=true: Disables lazy loading (eager mode).
• EAGER_IMPORT=0 or EAGER_IMPORT="": Re-enables lazy loading.

You can specify version requirements for external libraries using the require parameter in lazy.load. If the installed version does not meet the requirement, an error will be raised upon attribute access.

Note: The requirement must use the distribution name (e.g., pyyaml) rather than the import name (e.g., yaml).

import lazy_loader as lazy
np = lazy.load("numpy", require="numpy >=1.24")

Since static type checkers cannot infer types from lazy imports, use lazy.attach_stub to load type stubs (.pyi files). Note that when using this method, the .pyi files are required for both type checking and runtime execution.

import lazy_loader as lazy
__getattr__, __dir__, _ = lazy.attach_stub(__name__, "subpackages.pyi")

Use lazy.load to defer the import of external dependencies.

Important: Avoid loading subpackages directly (e.g., lazy.load('scipy.linalg')), as this will cause the parent package (scipy) to be imported immediately. Instead, load the base package and access the subpackage via attributes.

Immediate Error Checking: Use error_on_import=True to raise an ImportError as soon as lazy.load is called, rather than waiting for the module to be accessed.

import lazy_loader as lazy

# Standard lazy load
sp = lazy.load('scipy')
sp.linalg.norm(...)

# Load with immediate error checking
linalg = lazy.load('scipy.linalg', error_on_import=True)

You can use lazy.attach to lazily load both submodules and specific attributes (functions/classes) within those submodules. This is useful for exposing a flat API while keeping imports deferred.

from ..util import lazy

__getattr__, __dir__, __all__ = lazy.attach(
    __name__,
    submodules=['rank'],
    submod_attrs={
        '_gaussian': ['gaussian', 'difference_of_gaussians'],
        'edges': ['sobel', 'scharr', 'prewitt', 'roberts',
                  'laplace', 'farid']
    }
)

You can force lazy_loader to perform eager imports (loading everything immediately instead of on-demand) by setting the EAGER_IMPORT environment variable.

Set EAGER_IMPORT to any value other than '0' or an empty string to trigger eager loading of all attached submodules and attributes.

If you are using lazy loading via attach(), static type checkers might not be able to find your imports. attach_stub() solves this by parsing a .pyi stub file to automatically infer which submodules and attributes should be lazily loaded.

Parameters:

• package_name (str): Typically __name__.
• filename (str): Path to the .py file that has an adjacent .pyi stub file. Typically __file__.

Returns:

• A tuple containing (__getattr__, __dir__, __all__) identical to the output of attach().

__getattr__, __dir__, __all__ = attach_stub(__name__, __file__)