python-lazyimports 0.1.1

Backport of Python 3.15's lazy import statement.

lazyimports

A backport of Python 3.15's lazy import statement for older Python versions.

On Python 3.15+, you can write:

lazy import numpy
lazy from os.path import join

This package provides the same deferred-import behaviour on every supported Python version (3.6 through 3.15) via a small, focused API.

Why?

Deferring heavy imports until they are actually needed can noticeably speed up module load times and reduce memory usage — useful for CLIs, plugins, and any code path that imports optional dependencies.

Installation

pip install python-lazyimports

Usage

Lazy import

from lazyimports import lazy_import

np = lazy_import("numpy")          # not imported yet
pd = lazy_import("pandas")         # not imported yet

# ``numpy`` is loaded on first attribute access:
arr = np.array([1, 2, 3])

Lazy from X import Y

from lazyimports import lazy_from

join, basename = lazy_from("os.path", "join", "basename")
result = join("a", "b")            # os.path is imported here

Grouping with lazy()

from lazyimports import lazy, lazy_import

with lazy():
    np = lazy_import("numpy")
    pd = lazy_import("pandas")
    tf = lazy_import("tensorflow")
# None of the modules are imported until first use.

Inspecting and forcing load

from lazyimports import is_lazy, force_load

proxy = lazy_import("json")
assert is_lazy(proxy)
assert not is_lazy(json)           # False for already-imported modules

real = force_load(proxy)           # resolve now and return the real module

API

Symbol	Description
lazy_import(name, package=None)	Return a lazy proxy for module name.
lazy_from(module, *names)	Lazily import specific names from a module.
is_lazy(obj)	Return True if obj is a LazyModule.
force_load(obj)	Force resolution of a LazyModule; pass-through for anything else.
lazy()	Context manager for grouping lazy imports (no-op marker).
LazyModule	The proxy class returned by lazy_import().
NATIVE_LAZY_IMPORT	True when running on Python 3.15+.
SUPPORT_LAZY_IMPORT	True on every version (this package provides its own implementation).

Python 3.15+ native syntax

When you are running on Python 3.15+, you may prefer the native syntax. The package's own API still works identically, so you can use either:

# Native (Python 3.15+ only):
lazy import numpy

# Cross-version equivalent via this package:
from lazyimports import lazy_import
numpy = lazy_import("numpy")

Compatibility

• Python 3.6 through 3.15
• No third-party dependencies — uses only the standard library (contextlib, importlib, sys, types)

Running the tests

python -m unittest test_lazyimports -v

License

MIT