Skip to content

lazy-loading.md

Latest commit

 

History

History
82 lines (52 loc) · 2.92 KB

lazy-loading.md

File metadata and controls

82 lines (52 loc) · 2.92 KB

Lazy Loading

The project uses lazy_loader and mkinit to implement lazy loading of modules, which improves import performance by only loading modules when they are actually used.

Features

  • Improved Startup Time: Modules are only imported when actually used
  • Preserved Type Hints: Type hints are preserved through .pyi stub files
  • Automatic Generation: __init__.py files are automatically generated
  • Pre-commit Integration: Imports are kept up-to-date with pre-commit hooks

How It Works

Lazy loading works by replacing direct imports with proxy objects that only import the actual module when accessed. This is done using the lazy_loader package.

The mkinit tool automatically generates __init__.py and __init__.pyi files with the appropriate lazy loading imports.

Usage

When you create a new module, you don't need to manually update the __init__.py files. Instead, the pre-commit hook will automatically run mkinit to update them.

To manually update the __init__.py files:

uv run mkinit src --relative --lazy_loader_typed --recursive -w

Example

Here's an example of how lazy loading works:

# In __init__.py
# Original import without lazy loading
from .module1 import function1
from .module2 import function2

# When this module is imported, both module1 and module2 are loaded immediately.
# with lazy loading
# In __init__.py (generated by mkinit)
import lazy_loader


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

__all__ = ['function1', 'function2', 'module1', 'module2']

# When this module is imported, neither module1 nor module2 are loaded
# They will only be loaded when function1 or function2 are actually used

Benefits

  • Faster Application Startup: Only load what you need when you need it
  • Reduced Memory Usage: Don't load modules that aren't used
  • Circular Import Prevention: Lazy loading can help prevent circular import issues
  • Cleaner Code: No need to use complex import workarounds

Type Checking

To ensure type checking works correctly with lazy loading, mkinit generates .pyi stub files alongside the __init__.py files. These stub files contain the type information for the lazy-loaded modules.

IDE Integration with Cursor

Generated Files and AI-Assisted Development

The lazy loading system generates two types of files:

  1. __init__.py: Contains the lazy loading implementation
  2. __init__.pyi: Contains type hints for static type checkers

These files are automatically generated and maintained by the pre-commit hooks. While you shouldn't need to edit them manually, Cursor's AI capabilities help by:

  • Automatically generating and updating imports
  • Suggesting optimal lazy loading patterns
  • Detecting potential import performance issues
  • Helping refactor code for better module organization

For more information about IDE integration and settings, see IDE Setup.