exonware-xwlazy 1.0.1.72

Automation tool for missing-import dependency resolution with lazy install/loading across the eXonware suite.

⚡ xwlazy

Fewer "ModuleNotFoundError" detours. Optional auto-install and deferred imports inside a package scope you control, with import-name → PyPI-name mappings (bs4 → beautifulsoup4, etc.), PEP 668 awareness, and optional audit outputs.

Company: eXonware.com · Author: eXonware Backend Team · Email: [e-mail]

---

📦 Install

Requires Python 3.8+. (See pyproject.toml requires-python.)

Install	What you get	When to use
pip install exonware-xwlazy	Core lazy hook, curated import→PyPI mappings (xwlazy_external_libs.toml)	Opt-in lazy install/load for your library or app.

Same package; you can also install as xwlazy. This project does not define [lazy] / [full] extras on itself—use those extras on stack packages (e.g. exonware-xwsystem[lazy]) that depend on xwlazy.

• On a system interpreter, PEP 668 is respected: no silent installs into externally managed environments.
• Inside a venv, installs use that environment's pip.

---

🚀 Quick start

One-line enable (scoped to your package):

try:
    from exonware.xwlazy import config_package_lazy_install_enabled
    config_package_lazy_install_enabled(__package__ or "yourorg.yourlib", enabled=True, mode="smart")
except ImportError:
    # xwlazy not installed -> normal behavior (no lazy hook)
    pass

Normal import statements stay as they are. Inside the enabled scope you get lazy install and (when policy allows) lazy loading.

Zero-code opt-in (optional): in pyproject.toml:

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

After pip install -e ., lazy mode can turn on from package metadata.

Global-style helper:

from xwlazy import auto_enable_lazy

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

---

✨ What you get

Area	What's in it
Lazy install	First touch on a missing module can trigger pip install for the mapped package.
Lazy loading	Selected imports wait until use when your policy enables it.
Per-package scope	Each package opts in; others are unchanged.
Keyword opt-in	xwlazy-enabled in pyproject.toml enables without code.
Two-stage behavior	Import time: log and defer; use time: install then continue.
Policy / audit	Allow/deny lists, lockfile, SBOM hooks, PEP 668 checks.
Persist to project	Successful installs can append requirements.txt / pyproject.toml. Use XWLAZY_PERSIST_EXTRAS and XWLAZY_NO_PERSIST to control.

Runtime entry: src/exonware/xwlazy.py; src/xwlazy.py re-exports. src/_old/ is reference-only and is not shipped as the runtime entry.

---

🎯 Why xwlazy? (Highlights)

Built-in mappings - Curated table: src/exonware/xwlazy_external_libs.toml (data/ML, DL, viz, web, formats). Override or extend in your tree if you need custom rows.

Benchmarks vs other lazy-import tools - We run xwlazy next to pipimport, deferred-import, lazy-loader, lazy-imports, pylazyimports, lazi, lazy-imports-lite, etc. See benchmarks/20260209-benchmark competition/README.md. Latest campaign (Feb 2026, representative): medium_load ~4.06 ms (xwlazy) vs ~4.54 ms next best in that run; heavy_load / enterprise_load ~14 ms and ~41 ms with auto-install, isolation, and audit enabled. Many competitors only defer imports or assume import name == pip name; xwlazy adds mapping-aware installs, optional lockfile/SBOM, and per-package isolation.

Common footgun without mapping:

You write	Pip package	Without mapping
import bs4	beautifulsoup4	pip install bs4 often wrong
import yaml	PyYAML	pip install yaml fails
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	wrong package

Modes and strategies:

Strategy	Behavior	Typical use
smart	Uses manifests + mappings	Default
pip	Plain pip under the hook	Explicit pip semantics
wheel	Prefer wheels	Wheel-rich envs
cached	Reuse resolved candidates	Repeat runs

No activation → normal imports, no lazy behavior.

Security and production - Deny list in xwlazy_external_libs.toml ([deny_list]). Lockfile (opt-in): with auditing, ~/.xwlazy/xwlazy.lock.toml. Persist: writes to project requirements.txt / pyproject.toml unless disabled (XWLAZY_NO_PERSIST=1, XWLAZY_PERSIST_EXTRAS=...). SBOM (opt-in): generate_sbom() → ~/.xwlazy/xwlazy_sbom.toml when auditing is on. Async I/O (default): background worker for persist/lockfile/audit; XWLAZY_ASYNC_IO=0 forces sync. PEP 668: no installs into externally managed interpreters; use a venv. Set XWLAZY_AUDIT_ENABLED=1 before import if you want lockfile/SBOM writes (auditing is off by default). Production pattern: pin deps, pre-install in images, keep lazy as a safety net if you accept the trade-offs.

Optional mixins (off by default) - Per-call wrapper API, AST rewrite, and type-stub helpers exist behind env flags. We recommend leaving them off; they add complexity and are easy to miscompose with the core hook.

Feature	Env var
Per-call wrapper	XWLAZY_PER_CALL_API=1
AST lazy transform	XWLAZY_AST_LAZY=1
Type-stub tooling	XWLAZY_TYPING_TOOLS=1

Prefer config_package_lazy_install_enabled, auto_enable_lazy, or attach for normal work.

Troubleshooting:

from xwlazy import get_all_stats

stats = get_all_stats()

• Nothing installs: get_lazy_install_stats("your-package") - check enabled and mode, and allow lists.
• First import slow: first install cost; pre-install with [full] on stack packages or warm caches.

---

🧱 Implementation and the rest of the stack

Implementation: The main hook and strategies live in exonware/xwlazy.py (large single module by design). Supporting pieces include version.py, xwlazy_external_libs.toml, and thin re-export shims.

Ecosystem: xwlazy is optional glue for the eXonware stack: xwsystem and other packages use [lazy] / [full] to pull it in so missing format backends or optional deps can install on first use. Standalone use is fine for any Python project that wants mapping-aware lazy install behind an explicit opt-in.

---

📚 Full feature list and examples

For modes, persist-to-project, extension points, and production notes see docs/GUIDE_01_USAGE.md and docs/REF_15_API.md.

---

📖 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 - setup, modes, integration, troubleshooting.
• Requirements and status: docs/REF_01_REQ.md, docs/REF_22_PROJECT.md.
• API and design: docs/REF_15_API.md, docs/REF_13_ARCH.md.
• DX and quality: docs/REF_14_DX.md, docs/REF_50_QA.md, docs/REF_54_BENCH.md, docs/REF_51_TEST.md.
• Ideas and planning: docs/REF_12_IDEA.md, docs/REF_21_PLAN.md.
• Compliance: docs/REF_11_COMP.md. Evidence: docs/logs/ (benchmarks, tests). Benchmarks: benchmarks/INDEX.md, docs/logs/benchmarks/.

Tests: 3-layer suite (0.core, 1.unit, 2.integration). Run:

python tests/runner.py
# or: python tests/0.core/runner.py, python tests/1.unit/runner.py, python tests/2.integration/runner.py

See docs/REF_51_TEST.md.

---

🧭 Where xwlazy fits

xwlazy provides optional lazy install and lazy load hooks for libraries that opt in per package. Downstream eXonware packages depend on it through [lazy] / [full] extras (especially xwsystem) so developers can defer heavy or optional dependencies without rewriting import graphs.

• Mappings: Import names mapped to PyPI packages (not only import name == pip name).
• Policy: Allow/deny lists, PEP 668 awareness, optional lockfile/SBOM when auditing is enabled.
• Scope: Per-package activation; no global behavior until you enable it.

---

🌐 Ecosystem functional contributions

xwlazy is optional infrastructure: stack packages stay lean at install time while still offering a path to auto-install missing pieces on first use.

Downstream XW lib	What xwlazy provides to it	Functional requirement xwlazy covers
XWSystem	Optional [lazy] activation; missing format backends can install on first import.	Developer velocity without pinning every codec up front.
XWFormats / XWJSON / XWData / XWNode	Heavy or optional backends loaded or installed on demand when policy allows.	Smaller default installs; fewer import-time failures.
XWStorage / XWAPI / XWAuth	Same pattern for optional server-side or connector stacks behind policy.	Controlled optional surface area.
Other XW libs with [lazy]	Shared mapping table, audit hooks, persist-to-project.	Consistent lazy semantics across the ecosystem.

Improvements in xwlazy (mappings, policies, installers) propagate wherever [lazy] is adopted.

---

📜 License and links

Apache-2.0 - see LICENSE.

• Homepage: https://exonware.com
• Repository: https://github.com/exonware/xwlazy

Part of the eXonware ecosystem - optional lazy install/load for the stack and standalone projects.

⏱️ Async Support

• The xwlazy implementation under src/ is synchronous (no async/await in the core hook); a background worker handles optional file I/O (persist, lockfile, audit).
• Use xwlazy at import boundaries in async apps the same way you would any synchronous setup code.

Version: 1.0.1.72 | Updated: 08-Apr-2026

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