exonware-xwlazy 1.0.1.26

Marker package that enables lazy install features across the eXonware suite.

xwlazy ⚡️

Missing import? Install it on first use. One line to enable; standard imports, no try/except. Per-package isolation—xwsystem can be lazy while xwnode stays normal. 🚀

---

Install 📦

pip install exonware-xwlazy
# or
pip install xwlazy

Works in both local/system Python and virtual environments (venv, virtualenv, conda, uv, etc.):

• On a system interpreter, xwlazy respects PEP 668 and will refuse to install into externally-managed environments.
• Inside a venv, it simply uses the active environment’s pip — recommended for real projects.

---

Quick start 🚀

1. Enable for your package (one line in __init__.py):

from xwlazy import auto_enable_lazy

auto_enable_lazy(__package__)  # or auto_enable_lazy()

2. Use normal imports. First time a dependency is missing, xwlazy installs it; after that it’s a normal import. No changes elsewhere in your code.

Zero-code option: add to pyproject.toml:

[project]
keywords = ["xwlazy-enabled"]

Then pip install -e . — xwlazy picks it up from metadata.

---

What you get ⭐

Thing	What it means
On-demand install	Missing package → pip install when code first touches it. No manual install for optional features.
Per-package	Each package turns lazy on or off. xwsystem can be lazy, xwnode not—no cross-talk.
Keyword opt-in	"xwlazy-enabled" in pyproject → lazy on. No code change.
Two-stage load	Import time: missing imports logged, no crash. Use time: install then run. So you keep normal import style.
Control	Allow/deny lists, lockfile, SBOM. PEP 668 respected (no install into system Python).
Persist to project	On successful install, xwlazy can add the package to your requirements.txt and pyproject.toml (default: [project.optional-dependencies.full] if it exists, else [project.dependencies]). Set XWLAZY_PERSIST_EXTRAS=<name> to write into a specific extras group (e.g. dev) or XWLAZY_PERSIST_EXTRAS=none to force [project.dependencies]. Disable entirely with XWLAZY_NO_PERSIST=1.

DX highlights for developers ✨

• Copy-paste setup: pip install xwlazy + one auto_enable_lazy(...) call in your package __init__ and you’re done.
• No import gymnastics: Keep normal import statements; xwlazy installs missing deps behind the scenes, then gets out of your way.
• Works with how you already develop: Local/system Python or venv/conda/uv — with PEP 668 checks so you don’t accidentally mutate system installs.
• Debuggable behavior: get_lazy_install_stats(...), lockfile/SBOM outputs, and clear logs when something is skipped or denied — so you always know why something happened.

Single implementation file: src/exonware/xwlazy.py; src/xwlazy.py re-exports. When browsing on GitHub, you may see src/_old/ — this is legacy/reference code only, safe to ignore, and not shipped or imported.

---

Built-in library mappings

xwlazy ships with a curated mapping file (src/exonware/xwlazy_external_libs.toml) so common ecosystems “just work” out of the box:

• Data & ML: numpy, pandas, scipy, scikit-learn, statsmodels, xgboost, lightgbm, catboost, joblib, dask, …
• Deep learning & AI: torch, tensorflow/tf, keras, transformers, jax, jaxlib, …
• Visualization & geo: matplotlib, seaborn, plotly, bokeh, altair, graphviz, folium, geopandas, …
• Web & APIs: requests, httpx, aiohttp, fastapi, uvicorn, django, flask, starlette, …
• Formats & I/O: PyYAML, ruamel.yaml, beautifulsoup4 (bs4), pyarrow, fastavro, h5py, and more.

You can extend or override these mappings by editing that TOML file in your own project.

---

Why xwlazy? Benchmarked, mapping-aware, and feature-rich 🏆

We run xwlazy against other lazy-import libraries (pipimport, deferred-import, lazy-loader, lazy-imports, pylazyimports, lazi, lazy-imports-lite) in a dedicated benchmark campaign. Here’s what stands out.

Performance (latest competition run)

• Medium load: xwlazy is fastest (4.06 ms vs 4.54 ms next best).
• Heavy / enterprise: xwlazy stays in the top tier (e.g. 14.46 ms heavy, 41.37 ms enterprise) while keeping auto-install, per-package isolation, and audit features on.

So you get competitive or leading times without giving up mapping-aware installs or policy controls.

Feature comparison

Other tools are built for different trade-offs: many do lazy import only (no auto-install), or auto-install but assume import name == pip name. xwlazy is the only one in the comparison that has all of: auto-install, lazy import, global import hook, mapping-aware install, pyproject/build integration, import tracing, per-package isolation, lockfile/SBOM, PEP 668 awareness, and a one-liner API. See the Library Feature Comparison table in the campaign README.

Where other lazy installers break (no mapping)

Libraries that assume import name == pip package name will fail or install the wrong thing on very common imports. Examples:

You write	Pip package to install	What happens without mapping
import bs4	beautifulsoup4	They run pip install bs4 → wrong or missing.
import yaml	PyYAML	pip install yaml → fails (no such package).
import sklearn	scikit-learn	pip install sklearn → fails.
import cv2	opencv-python	pip install cv2 → fails.
import PIL	Pillow	pip install PIL → fails.
import attr	attrs	pip install attr → wrong package.
import pandas	pandas	Same name, so may work—but import sklearn or import bs4 in the same project won’t.

xwlazy’s curated mapping (xwlazy_external_libs.toml) resolves these so that import bs4, import yaml, import sklearn, import cv2, import PIL, etc. install the correct pip package automatically. No per-import configuration or wrapper API needed.

---

Modes and strategies 🎛️

xwlazy combines when to install (lazy vs normal imports) with how to install (strategy):

Strategy	What it does	Use when
smart	Uses manifests and mappings to install missing deps on first use.	Default for most projects.
pip	Installs missing deps with plain pip under the lazy import hook.	You want vanilla pip behavior.
wheel	Prefers wheel-based installs when available.	Environments with prebuilt wheels.
cached	Reuses previously resolved install candidates across runs.	Repeat runs with similar deps.

If you don’t call auto_enable_lazy(...), imports stay normal and nothing is installed lazily.

Example:

from xwlazy import auto_enable_lazy

auto_enable_lazy("xwsystem", mode="smart")

---

Security and production 🛡️

• Deny list: a central list of blocked packages loaded from the [deny_list] section in xwlazy_external_libs.toml.
• Lockfile (opt-in): when auditing is enabled, installed packages and basic stats persist to ~/.xwlazy/xwlazy.lock.toml for reproducibility.
• Persist to project: when an install succeeds, xwlazy adds the package to your project’s requirements.txt and/or pyproject.toml (default: [project.optional-dependencies.full] if present, else [project.dependencies]). Override with XWLAZY_PERSIST_EXTRAS=<name> (write to that extras group) or XWLAZY_PERSIST_EXTRAS=none (force dependencies). Disable with XWLAZY_NO_PERSIST=1.
• SBOM (opt-in): when auditing is enabled, generate_sbom() writes ~/.xwlazy/xwlazy_sbom.toml so you can audit what was installed and when.
• Async I/O (default): file updates (persist-to-project, lockfile, audit log) run in a background worker so imports/installs don’t block your app. Set XWLAZY_ASYNC_IO=0 to force synchronous writes.
• PEP 668: xwlazy won’t install into externally-managed environments; it will tell you to use a venv instead.

Auditing is disabled by default. To enable lockfile/SBOM writes, set XWLAZY_AUDIT_ENABLED=1 in the environment before importing xwlazy.

For production, you typically pre-install pinned dependencies, keep the lazy hook in smart or pip strategy for edge cases, and (optionally) rely on the lockfile/SBOM for audit.

---

Optional features (we recommend against enabling) ⚠️

Three optional mixins exist for per-call wrapper API, AST rewrite, and type-stub / internal API tooling. They are disabled by default and only activate when you set the corresponding environment variable:

Feature	Env var	API when enabled
Per-call wrapper API	XWLAZY_PER_CALL_API=1	lazy_import(module_name, package=..., mode=..., root=...)
AST rewrite / lazy transform	XWLAZY_AST_LAZY=1	enable_ast_lazy(root=...), disable_ast_lazy()
Type-stub / internal API tooling	XWLAZY_TYPING_TOOLS=1	attach_stub(package_name, stub_content=..., stub_path=...), get_stub_registry()

From a software engineering perspective we recommend against enabling these. They increase complexity, reduce maintainability, and (for AST/type-stub) are fragile or address a different problem domain. When enabled, they may or may not work well together (e.g. per-call and AST both touching imports). Prefer the core hook / auto_enable_lazy / attach API. Enable only for edge cases or compatibility.

---

Troubleshooting 🩺

See what’s going on:

from xwlazy import get_all_stats

stats = get_all_stats()  # installed_packages, failures, lockfile_path, keyword detection, etc.

“Nothing gets installed”: Check get_lazy_install_stats("your-package") — enabled and mode. If you use an allow list, the package must be in it.

First import slow: That’s the first install. Use full to pre-install everything, or lite and install deps yourself; caching is on by default.

---

Docs and tests 📚

Content in this README is aligned with the project REFs and docs/GUIDE_01_USAGE.md (per GUIDE_63_README).

• Start: docs/INDEX.md — doc index and quick links.
• Use it: docs/GUIDE_01_USAGE.md — modes, integration, production, troubleshooting.
• Requirements and status: docs/REF_01_REQ.md, docs/REF_22_PROJECT.md.
• API and DX: docs/REF_15_API.md, docs/REF_14_DX.md.
• Architecture: docs/REF_13_ARCH.md.
• Quality: docs/REF_54_BENCH.md, docs/REF_51_TEST.md. Benchmark run logs: docs/logs/benchmarks/.

Tests:

python tests/runner.py
# or per layer: python tests/0.core/runner.py, python tests/1.unit/runner.py

See docs/REF_51_TEST.md for test layers and coverage.

---

🔬 Innovation: Where does this package fit?

Tier 1 — Genuinely novel (nothing like this exists)

xwlazy — Adaptive Intelligent Package Manager

Not just lazy imports — an adaptive import hook that learns from usage patterns. Multi-tier caching (in-memory LRU + disk cache), manifest-based discovery, a deny list for problematic packages, and optional SBOM/lockfile support.

• functools.lru_cache = one cache type; xwlazy layers caching, manifest indexing, and an adaptive installer with optional lockfile (~/.xwlazy/xwlazy.lock.toml) and SBOM (~/.xwlazy/xwlazy_sbom.toml) output for audit (off by default; enable with XWLAZY_AUDIT_ENABLED=1).

Verdict: 🟢 Nothing like this exists as a unified system. Part of the eXonware story — vertical integration across 20+ packages.

---

License and links 🔗

MIT — see LICENSE.

• Homepage: https://exonware.com
• Repository: https://github.com/exonware/xwlazy
• Contact: [e-mail] · eXonware Backend Team

Version: See version.py or PyPI. Updated: See version.py (__date__).

Built with ❤️ by eXonware.com - Revolutionizing Python Development Since 2025