lateimport

Lazy import utilities for Python — defer module loading until an imported object is actually used.

Status: Stable. Feature complete. Open to suggestions for API improvements and will fix bugs.

Overview

lateimport provides two complementary tools:

• lateimport — an explicit proxy for deferring imports in application code
• create_late_getattr — a factory for the __getattr__ hook in package __init__.py files, for use with dispatch-table-based lazy loading (e.g. as generated by Exportify)

We developed lateimport for CodeWeaver, and we liked it so much we decided to ship it as its own package for other projects. It has been rigorously tested and has complete test coverage.

Dependency Free. Lightweight.

• lateimport is purely stdlib -- zero outside dependencies.
• Small package -- the whole implementation is ~280 lines of code. For that you get modern typing and type checker support, and truly lazy imports.

Why?

There are a lot of late/lazy/delayed import solutions out there. Lateimport's main differences:

• Complete type checking support
• Actually lazy. Most lazy patterns delay until the lazy object is in scope. lateimport delays imports until they are actually directly accessed (i.e. you access an attribute or call it).
• Get linting and automation with Exportify. Exportify is a CLI development tool that lets you declaratively set rules for import and export patterns, and validate all lazy imports from lateimport. You can say goodbye to broken lazy imports and updating __all__.

Requirements

Python 3.12+

Installation

pip install lateimport

Usage

Explicit lazy imports

Use lateimport when you want to defer a heavy import in application code. The module is not imported until the returned proxy is actually used — called, subscripted, passed to isinstance, etc.

from lateimport import lateimport

# No import happens here
numpy = lateimport("numpy")
pandas = lateimport("pandas", "DataFrame")  # defers pandas.DataFrame

# Import triggered on first use
result = numpy.array([1, 2, 3])
df = pandas({"a": [1, 2]})

Proxies are thread-safe and cache the resolved object after first access.

proxy = lateimport("heavy.module", "ExpensiveClass")

proxy.is_resolved()   # False
instance = proxy()    # heavy.module imported, ExpensiveClass resolved
proxy.is_resolved()   # True

Type annotations

LateImport[T] is a generic class. Annotating a variable with the resolved type gives you full type-checking and autocompletion downstream — the type checker knows that calling or accessing the proxy produces a T.

from __future__ import annotations

from typing import TYPE_CHECKING

from lateimport import LateImport, lateimport

if TYPE_CHECKING:
    import numpy as np
    from pandas import DataFrame

# Type checker knows ndarray() returns np.ndarray
ndarray: LateImport[np.ndarray] = lateimport("numpy", "ndarray")
arr = ndarray([1, 2, 3])  # arr: np.ndarray

# type[DataFrame] means calling the proxy produces a DataFrame instance
DataFrame: LateImport[type[DataFrame]] = lateimport("pandas", "DataFrame")
df = DataFrame({"col": [1, 2, 3]})  # df: DataFrame

Important

The TYPE_CHECKING guard keeps the imports from executing at runtime — you get static type information without the import cost, which is the whole point.

For types that are always available no guard is needed:

from pathlib import Path
from lateimport import LateImport, lateimport

MkPath: LateImport[type[Path]] = lateimport("pathlib", "Path")
p = MkPath("/tmp/out")  # p: Path

Package-level lazy __getattr__

For packages using a dispatch-table pattern (e.g. generated by Exportify, create_late_getattr creates a __getattr__ hook that imports attributes on demand:

# mypackage/__init__.py
from types import MappingProxyType
from lateimport import create_late_getattr
# NOTE: for IDE support, import any dynamic imports in a TYPE_CHECKING block:
from typing import TYPE_CHECKING:
    from mypackage.core.models import MyClass
    from mypackage.utils.helpers import my_function
    from mypackage import SubModule

_dynamic_imports = MappingProxyType({
    "MyClass":      ("mypackage.core",   "models"),
    "my_function":  ("mypackage.utils",  "helpers"),
    # for the current package you can just use __spec__.parent:
    "SubModule":    (__spec__.parent,        "__module__"),
})

__getattr__ = create_late_getattr(_dynamic_imports, globals(), __name__)

__all__ = ("MyClass", "my_function", "SubModule")

# Make sure dir calls use __all__ and not globals:
__dir__ = lambda: list(__all__)

The dispatch tuple is (package, submodule):

• Normal attributes: imports package.submodule and returns getattr(submodule, attr_name)
• "__module__": imports the submodule itself as the attribute (import_module(f".{attr_name}", package=package))

Resolved attributes are cached in globals() so subsequent accesses are direct.

API

lateimport(module_name, *attrs) -> LateImport[T]

Create a lazy proxy for module_name. Optional attrs are an attribute chain traversed after import. The function is generic — annotate the variable as LateImport[T] to propagate the resolved type to callers.

lateimport("os")                    # proxy for the os module
lateimport("os.path", "join")       # proxy for os.path.join
lateimport("mypackage", "A", "B")   # proxy for mypackage.A.B

class LateImport[T]

The generic proxy class returned by lateimport. Annotate the variable with LateImport[T] to tell the type checker what type the proxy resolves to — __call__ and _resolve() are typed to return T. Supports call, attribute access, dir(), and repr(). Thread-safe.

Method	Description
is_resolved()	True if the import has been triggered
_resolve()	Force immediate resolution and return the object (typed as T)

create_late_getattr(dynamic_imports, module_globals, module_name)

Create a __getattr__ function for package-level lazy loading.

Parameter	Type	Description
dynamic_imports	MappingProxyType[str, tuple[str, str]]	Dispatch table
module_globals	dict[str, object]	globals() of the calling module
module_name	str	__name__ of the calling module

INTROSPECTION_ATTRIBUTES

frozenset of dunder attribute names that are resolved immediately rather than proxied (e.g. __doc__, __name__, __module__). Available for reference when implementing custom proxy patterns.

License

MIT OR Apache-2.0 — see LICENSE-MIT and LICENSE-Apache-2.0.