laziest-import

Table of Contents

• Key Features
• Quick Start
• Installation
• Terminal Demo
• Examples
• Configuration
• API Reference
• Troubleshooting
• How It Works
• Contributing
• License

Key Features

Feature	Badge	Description
Lazy Loading		Modules import only on first access
Background Index		Symbol index builds in background thread
Auto-Correction		Typo correction (nump → numpy)
Symbol Search		Search symbols across all modules
Strict Mode		AmbiguousSymbolError on symbol conflicts
Multi-Level Cache		Three-tier caching for speed
Dependency Analysis		Analyze module dependencies
Performance Benchmark		Benchmark imports and functions
CLI Interface		laziest-import freeze / init / fix commands
Symbol Autocomplete		Prefix-based symbol name completion
1065+ Tests		Comprehensive test coverage
1000+ Aliases		Predefined for common packages

Installation

# Stable version
pip install laziest-import

# Pre-release version (latest features)
pip install --pre laziest-import

# From source (latest development)
pip install git+https://github.com/ChidcGithub/Laziest-import.git

Quick Start

Method 1: Wildcard Import (Recommended)

from laziest_import import *

# Data Science
arr = np.array([1, 2, 3]) # numpy
df = pd.DataFrame({'a': [1, 2]}) # pandas
plt.plot([1, 2, 3]); plt.show() # matplotlib

# Standard Library
print(os.getcwd()) # os
data = json.dumps({'key': 'value'}) # json
result = math.sqrt(16) # math

# Submodules (auto-loading)
svd_result = np.linalg.svd(matrix) # numpy.linalg.svd()

Method 2: Namespace Prefix (Recommended)

from laziest_import import lz

arr = lz.np.array([1, 2, 3])
df = lz.pd.DataFrame({'a': [1, 2]})

Method 3: Lazy Proxy (with Auto-Correction)

from laziest_import import lazy

# Automatic typo correction
arr = lazy.nump.array([1, 2, 3]) # nump -> numpy 
df = lazy.pnda.DataFrame() # pnda -> pandas 
arr2 = lazy.nupi.array([4, 5, 6]) # nupi -> numpy 

# Submodule shortcuts
layer = lazy.nn.Linear(10, 5) # nn -> torch.nn 
relu = lazy.F.relu(tensor) # F -> torch.nn.functional 

Key Features

What's New

v1.0.1.0 (Current)

• Type-stub (.pyi) symbol indexing — the index builder now parses .pyi stub files first, falling back to import-based scanning only when no stub exists:
  • Zero import side effects: modules are never executed during index building
  • Much faster on heavy packages (matplotlib: ~4ms vs ~160ms)
  • Precise type signatures extracted for free
  • Toggle: _config._STUB_INDEX_CONFIG["enabled"]; stats: get_symbol_cache_info()["stub_scanned_modules"]

v1.0.0.7

• Safety: auto-install fallback now respects the enabled switch (default off) — no unexpected pip prompts or subprocesses on import failure
• Correctness: module priorities now loaded from mappings/priorities.json; incremental symbol builds no longer overwrite a complete index with partial data; single exact-match symbols resolve reliably
• Concurrency: snapshot iteration over shared caches eliminates RuntimeError during background index builds; BackgroundIndexBuilder race/stop/timeout semantics fixed
• Persistence: atomic (tmp + replace) JSON cache writes; corrupt-tolerant cache loading; cache size accounting and cleanup actually work
• Windows/CJK: pip output forced to UTF-8 decoding; file-unlink protection when caches are held by other processes
• Benchmarks & Profiler: failed iterations excluded from timings, submodule caches cleared between runs, memory profiling uses tracemalloc.get_traced_memory()
• Plus 10+ smaller fixes: underscore-probe guards on proxies, alias remap/reload consistency, async retry wiring, hook error logging, dependency-tree accuracy

v1.0.0.6

• Comprehensive Bug Fixes: 8 critical bugs fixed including module_access_counts reset, LazySymbol None-value infinite re-import, hash/eq contract violation, _scan_path_modules returning after first sys.path entry, reset_all() wrong module reference, and get_symbol_help() broken attribute access
• Thread Safety: Lock protection added to _ALIAS_MAP writes, negative cache, invalidate_package_cache, and hook removal
• Python 3.9 Compatibility: Any | None union syntax replaced with Optional[Any] for older Python support
• Version Comparison Fix: Prerelease version strings now correctly compare numeric suffixes (e.g. alpha10 vs alpha2)
• Config System Fix: Environment variables now have highest priority; interactive override parameter respected in auto-install
• Cache Fixes: Cleanup limited to laziest_*.json prefix; max_cache_size_mb=0 treated as unlimited; partial cache load no longer prevents full rebuild
• which() Improvement: Returns None on module hint mismatch instead of silent wrong fallback
• License/CI: timeout-minutes added to GitHub Actions workflows preventing 6-hour CI hangs
• Environmental Cleanup: Removed outdated migration guide, orphaned debug scripts, and unused binary artifacts

New Features

• Reflected Operators: LazySymbol now supports __radd__, __rsub__, __rmul__, __rtruediv__, __rfloordiv__, __rmod__, __rpow__, __rmatmul__, __neg__, __pos__, __abs__, __invert__
• Async Retry Logic: _async_ops.py now implements actual retry based on _RETRY_CONFIG
• CLI fix Command: laziest-import fix generates standard import statements from lazy alias usage
• Symbol Autocomplete: symbol_autocomplete(prefix) for prefix-based symbol name completion
• Build Progress API: BackgroundIndexBuilder.get_progress() for querying current build state
• which_all Live Search: Now performs live search even after index is built, catching newly installed modules
• Lazy Registry Management: Added unregister() and list_registered() to _lazy_registry.py
• Terminal Demo: Interactive animated demo at examples/terminal_demo.py

Code Quality

• 10+ broad except Exception narrowed to specific exceptions
• sys.path.insert(0, '.') removed from test files
• Trivially-true is True or is False assertions replaced with isinstance(bool)
• Redundant x as x imports removed from _symbol/ redirect files
• Duplicated SymbolIndexCache dataclass consolidated to single definition
• _is_stdlib_module performance improved via module-level constant set
• import time relocated to top of _cache/_file_cache.py
• Test count and version unified across READMEs

v0.1.0

• Phase 5 — Fake Code Audit & Fix: All placeholder/fake code replaced with real logic
• Fixed assert True tests: 4 tests replaced with real assertions
• Fixed silent except Exception: pass: 4 tests, HookList.__call__(), _benchmark.py warmup/measure, _state_setters.py narrowed to except ImportError
• Fixed 48 zero-assertion smoke tests: Added type/value assertions
• Fixed _jupyter.py unload_ipython_extension(): No-op pass replaced with unregister_magics()
• Fixed _cache/_api.py invalidate_package_cache(): Added missing _STDLIB_SYMBOL_CACHE cleanup
• Fixed circular import in _build_known_modules_cache(): Skip scanning CWD (''/'.' paths) to prevent re-import of scripts in working directory
• 1065 tests: All passing, comprehensive coverage

Terminal Demo

Run the interactive terminal demo to see laziest-import in action with animated visuals:

python examples/terminal_demo.py

  /=======================================\
  |   laziest-import  Terminal Demo        |
  \=======================================/
  [1] Import everything with one line
     -> np.array([1,2,3])     = [1 2 3]
     -> math.sqrt(144)        = 12.0
     -> os.getcwd()           = /home/user
  [2] Submodules auto-load
     -> os.path.join('a','b') = a/b
  [3] Symbol search across all modules
     -> math.sqrt  (function)
     -> numpy.sqrt (function)
  ...
  

Symbol Search & Location

import laziest_import as lz

# Search for a symbol across all modules
results = lz.search_symbol('DataFrame')
for result in results:
 print(f"{result.module_name}.{result.symbol_name}")

# Find where a symbol is defined
loc = lz.which('sqrt')
print(f"Found at: {loc}") # numpy.sqrt

# Find all occurrences
locs = lz.which_all('sqrt')
for loc in locs:
 print(f"{loc.module_name}.{loc.symbol_name}")

Dependency Tree Analysis

import laziest_import as lz

# Analyze a module's dependency tree
tree = lz.dependency_tree('numpy', max_depth=2)
print(f"Total modules: {tree.total_modules}")
print(f"Stdlib: {tree.stdlib_count}, Third-party: {tree.third_party_count}")

# Print formatted tree
lz.print_dependency_tree(tree)

Performance Benchmarking

import laziest_import as lz

# Benchmark a function
result = lz.benchmark(
 lambda: sum(range(10000)),
 name="sum_test",
 iterations=100,
 warmup=10
)
print(f"Avg: {result.avg_time*1000:.4f}ms")
print(f"Min: {result.min_time*1000:.4f}ms")
print(f"Max: {result.max_time*1000:.4f}ms")

# Benchmark module imports
report = lz.benchmark_imports(['numpy', 'pandas', 'matplotlib'])
lz.print_benchmark_report(report)

Strict Mode (Symbol Conflict Detection)

from laziest_import import lz

# Enable strict mode
lz.symbol.config.strict = True

# Multiple modules define `sqrt` — raises AmbiguousSymbolError
# result = lz.sqrt  # Error: sqrt found in numpy, math, scipy, ...

# Use prefer() to resolve ambiguity
lz.symbol.prefer("sqrt", "numpy")
result = lz.sqrt(16)  # Now resolves to numpy.sqrt

CLI: Freeze, Fix & Init

# Scan project and freeze alias usage
laziest-import freeze

# Generate standard import statements from lazy alias usage
laziest-import fix

# Generate .laziestrc config file
laziest-import init

The freeze command produces imports.laziest.json — a manifest of all lazy imports used across your project, ideal for CI validation.

The fix command generates standard Python import X as Y statements from detected lazy alias usage — useful when migrating from lazy imports to explicit imports.

Auto-Install (Optional)

from laziest_import import *

# Enable auto-install
lz.enable_auto_install()

# Accessing uninstalled modules triggers installation
arr = np.array([1, 2, 3]) # If numpy missing, prompts to install

Configuration

User Configuration

import laziest_import as lz

# Create default config file
lz.create_rc_file()

# Load config
config = lz.load_rc_config()

# Get specific value
value = lz.get_rc_value('debug', default=False)

# Config info
info = lz.get_rc_info()

Cache Configuration

import laziest_import as lz

# Set custom cache directory
lz.set_cache_dir('./my_cache')

# Configure cache settings
lz.set_cache_config(
 symbol_index_ttl=3600, # Symbol index TTL: 1 hour
 stdlib_cache_ttl=2592000, # Stdlib cache TTL: 30 days
 max_cache_size_mb=200 # Max cache size: 200 MB
)

# Get cache statistics
stats = lz.get_cache_stats()
print(f"Hit rate: {stats['hit_rate']:.1%}")

# View cache status
info = lz.get_file_cache_info()
print(f"Cache size: {info['cache_size_mb']:.2f} MB")

API Reference

Alias Management

Symbol Search

Auto-Install

Cache Management

Analysis & Profiling

Preferences

Troubleshooting

Common Issues

Q: Module not found (AttributeError)

AttributeError: module 'laziest_import' has no attribute 'mymodule'

Solution: The module is not registered. Use lz.config.auto_search = True to enable auto-discovery, or register it manually:

lz.alias.register('mymodule', 'mypackage.mymodule')

Q: Slow first import The symbol index may be building. Check status with:

lz.background.is_building  # True if building
lz.background.wait(timeout=30)  # Wait up to 30 seconds

Q: Typo correction not working Ensure the module is in the alias list:

lz.alias.register('nump', 'numpy')  # Add misspelling
arr = lz.nump.array([1, 2, 3])  # Now works

Q: Symbol conflicts (same name in multiple modules) Use module hints or preferences:

lz.symbol.prefer('DataFrame', 'pandas')  # Prefer pandas
result = lz.DataFrame  # Gets pandas.DataFrame

Debug Mode

Enable detailed logging:

lz.config.debug = True
arr = lz.np.array([1, 2, 3])  # See import details in logs

Cache Issues

Clear caches if experiencing stale data:

lz.cache.clear()            # Clear memory cache
lz.cache.files.clear()       # Clear disk cache
lz.symbol.index.rebuild()    # Rebuild symbol index

Performance Tips

1. First run: ~2s to build index
2. Cached run: ~0.003s (700x faster!)
3. Use lz.background.enable(True) to avoid blocking on first import
4. For CI/CD, set LAZY_BG_BUILD=1 to pre-build cache

How It Works

Architecture

1. Proxy objects: Each alias maps to a LazyModule proxy
2. On-demand import: Real import triggers on first attribute access via __getattr__
3. Caching: Imported modules cache within the proxy object
4. Chain proxies: LazySubmodule handles recursive lazy loading
5. Fuzzy search: Levenshtein distance algorithm for fault-tolerant matching

Multi-Level Cache Architecture

The library uses a three-tier caching system for optimal performance:

Cache files are stored in ~/.laziest_import/cache/ and automatically:

• Expire based on TTL settings
• Clean up when exceeding size limit (default: 100 MB)
• Invalidate on Python version changes

Predefined Aliases

Data Science

np, pd, plt, sns, scipy

Machine Learning

torch, tf, keras, sklearn, xgboost, lightgbm

Deep Learning

transformers, langchain, llama_index

Web Frameworks

flask, django, fastapi, starlette

HTTP Clients

requests, httpx, aiohttp

Databases

sqlalchemy, pymongo, redis, duckdb

Cloud Services

boto3 (AWS), google.cloud, azure

Image Processing

cv2, PIL.Image, skimage

GUI

PyQt6, tkinter, flet, nicegui

DevOps

docker, kubernetes, ansible

NLP

spacy, nltk, transformers

Visualization

plotly, bokeh, streamlit, gradio

Contributing

We love contributions! Check out our Contributing Guide for more information.

How to Contribute

1. Fork the repo and create your branch from main
2. Read our Code of Conduct
3. Make sure your code lints (flake8)
4. Add tests for any new functionality
5. Ensure the test suite passes (pytest tests/)
6. Commit your changes
7. Push to your branch and open a Pull Request!

Development Setup

# Clone the repo
git clone https://github.com/ChidcGithub/Laziest-import.git
cd Laziest-import

# Install in development mode
pip install -e ".[dev,test]"

# Run tests
pytest tests/ -v

# Run linting
flake8 laziest_import/

Good First Issues

Looking for a place to start? Check out:

• Good first issues: Issues labeled "good first issue"
• Help wanted: Issues labeled "help wanted"

Ways to Contribute

• Report bugs
• Propose new features
• Improve documentation
• Fix existing issues
• Add more tests
• Help with translations
• Design improvements

Contributors

Thanks goes to these wonderful people:

Made with contrib.rocks.

Star History

Get In Touch

• Email: (your email)
• GitHub: ChidcGithub/Laziest-import
• Discussions: GitHub Discussions
• Issues: GitHub Issues

Acknowledgments

• Thanks to all the contributors who have helped make this project better!
• Inspired by the Python community's love for clean, simple APIs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Show Your Support

If you find this project useful, please consider:

• Starring this repo on GitHub
• Reporting bugs or suggesting features
• Sharing it with friends and colleagues
• Blogging about it if you use it
• Contributing to the project

Thank you!