Skip to content

import_lazy

LazyImport 

LazyImport(module_name: str, attr_name: str | None = None, verbose: bool = False)

Bases: Generic[LazyValueT]

A lazy import that loads the actual object on first access.

Source code in stdl/import_lazy.py 
14
15
16
17
18
19
20
21
22
23
24
def __init__(
    self,
    module_name: str,
    attr_name: str | None = None,
    verbose: bool = False,
) -> None:
    self.module_name = module_name
    self.attr_name = attr_name
    self.verbose = verbose
    self._cached_value: LazyValueT | None = None
    self._loaded = False

import_lazy 

import_lazy(module: str, names: list[str] | None = None, alias: str | None = None, verbose: bool = False) -> None

Lazy import a module.

Parameters:

Name Type Description Default
module str

Module name to import

 required
names list[str] | None

List of specific names to import from the module. If None, imports the module itself.

 None
alias str | None

Alias to use for the imported module (only valid when names is None)

 None
verbose bool

If True, print timing information when imports actually happen

 False
Example 
>>> import_lazy("module", ["name_1", "name_2"])  # from module import name_1, name_2
>>> import_lazy("module")                      # import module
>>> import_lazy("module", alias="mod")          # import module as mod
>>> import_lazy("package.submodule", ["name_1"])   # from package.submodule import name_1
Source code in stdl/import_lazy.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def import_lazy(
    module: str,
    names: list[str] | None = None,
    alias: str | None = None,
    verbose: bool = False,
) -> None:
    """
    Lazy import a module.

    Args:
        module (str): Module name to import
        names (list[str] | None): List of specific names to import from the module. If None, imports the module itself.
        alias (str | None): Alias to use for the imported module (only valid when names is None)
        verbose (bool): If True, print timing information when imports actually happen

    Example:
        ```python
        >>> import_lazy("module", ["name_1", "name_2"])  # from module import name_1, name_2
        >>> import_lazy("module")                      # import module
        >>> import_lazy("module", alias="mod")          # import module as mod
        >>> import_lazy("package.submodule", ["name_1"])   # from package.submodule import name_1
        ```
    """
    try:
        frame = sys._getframe(1)  # noqa: SLF001 - intentionally avoid importing inspect here.
    except ValueError as exc:
        raise RuntimeError("Cannot determine caller frame for lazy import") from exc

    caller_globals = frame.f_globals

    if names is None:
        lazy_import = LazyImport(module, verbose=verbose)
        if alias:
            caller_globals[alias] = lazy_import
        else:
            caller_globals[module.rsplit(".", maxsplit=1)[-1]] = lazy_import
    else:
        if alias:
            raise ValueError("Cannot use alias with named imports")

        for name in names:
            lazy_import = LazyImport(module, name, verbose=verbose)
            caller_globals[name] = lazy_import