Lazy Imports

1.2.0 · active · verified Sat Apr 11

lazy-imports is a Python library (current version 1.2.0) designed to facilitate lazy loading of modules and symbols, primarily to reduce application startup times. It provides decorators and functions to defer the actual import process until the imported object is first accessed. The library is actively maintained with updates released as needed.

Warnings

gotcha Lazy imports can interfere with IDE auto-completion, refactoring tools, and static analysis (e.g., MyPy), potentially leading to 'unresolved reference' warnings or missing type hints.
Fix: Use type-checking comments (`if TYPE_CHECKING: import ...`) or stub files (`.pyi`) to provide type information for static analysis without triggering eager imports, or accept reduced IDE support.
gotcha Debugging code with lazy imports can be challenging as the actual module import happens at the point of first access, not at the `lazy_import` definition, which can lead to unexpected exceptions or load delays at runtime.
Fix: Be aware of the deferred loading mechanism. Temporarily replace lazy imports with direct imports for intense debugging sessions, or set breakpoints strategically where the lazy object is first used.
gotcha While lazy imports can defer the *resolution* of circular dependencies, they do not fundamentally solve circular import *design* issues and can sometimes mask them, leading to runtime errors if not handled carefully.
Fix: Prioritize refactoring to eliminate circular dependencies. Use lazy imports only as a last resort or for specific performance optimizations where a cycle is unavoidable and well-understood.
gotcha Lazy imports introduce a small, one-time runtime overhead when the imported object is first accessed, as the module must then be loaded. For very frequently accessed or extremely small modules, this overhead might outweigh startup time benefits.
Fix: Profile your application to ensure that the performance benefits of lazy loading outweigh the first-access overhead in critical paths. Use lazy imports strategically for larger, less frequently accessed modules or for startup-critical paths.

Install

pip install lazy-imports Install stable version

Imports

lazy_import
```
from lazy_imports import lazy_import
```
The core function is directly available under the top-level package name.
lazy_module
```
from lazy_imports import lazy_module
```
The decorator is directly available under the top-level package name.
lazy_import_all
```
from lazy_imports import lazy_import_all
```
The function to import all symbols from a module is directly available.

Quickstart

This example demonstrates how to lazily import a specific function (`loads` from `json`) using `lazy_import`. The `json` module is only loaded into memory when `loads` is first invoked, illustrating the startup performance benefit.

from lazy_imports import lazy_import

# Defer import of 'json' module's 'loads' function
# The 'json' module will only be loaded when 'loads' is first called.
loads = lazy_import("json", "loads")

print("json.loads not yet imported...")
data = loads('{"key": "value"}') # The actual 'json' import happens here
print(f"Data loaded: {data}")

# Example with a module (using the decorator)
# from lazy_imports import lazy_module
# @lazy_module("os")
# def get_path_sep():
#     return os.path.sep

# print(f"Path separator: {get_path_sep()}")

view raw JSON →