xwlazy 1.0.1.88

Convenience wrapper for exonware-xwlazy - provides 'import xwlazy' alias

⚡ xwlazy

Fewer "ModuleNotFoundError" detours — for solo devs, small libraries, and big stacks alike. 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. No venv required unless your OS Python is externally managed; see Install below.

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	Canonical distribution: full wheel from this repo (see pyproject.toml)	Libraries and apps that want the supported package name.
pip install xwlazy	Thin PyPI alias that depends on exonware-xwlazy (pyproject.xwlazy.toml); enables import xwlazy	Ergonomics only—same feature set once installed.

Metadata source of truth: This repository declares Apache-2.0 and Python ≥3.8 for both names. If a PyPI page still shows something else (wrong license, stricter Python, or “only library that auto-installs” copy), treat it as stale and republish from these manifests—auto-install-on-import also exists in projects such as deferred-import and legacy pipimport.

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.

• You do not need a virtual environment. Lazy install runs python -m pip install for whatever interpreter is running (sys.executable). That works for a venv, a conda env, or a classic “global” Python as long as it is not PEP 668–restricted.
• PEP 668 (externally managed): many distro Pythons ship an EXTERNALLY-MANAGED file under sys.prefix. In that case xwlazy skips auto-install by default (no silent bypass of the OS package policy). Use a venv/conda env, install deps yourself, or set XWLAZY_ALLOW_EXTERNALLY_MANAGED=1 only on interpreters you deliberately want pip to modify.

---

🚀 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.

Prior art (auto-install is not new) — Install-on-missing-module predates xwlazy; deferred-import (lazy proxy + pip when missing; package= when import name ≠ PyPI name) and pipimport (global hook; often import name == pip name) are well-known examples. A deferred-import vs xwlazy breakdown (API, mapping model, policy, stack integration) lives in the benchmark campaign README (not shipped as vendored upstream code).

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. In the Feb 2026 campaign, medium_load was often fastest for xwlazy (~4.06 ms vs ~4.54 ms next in that slice); light, heavy, and enterprise runs sometimes favor slimmer libraries—raw speed is not uniform. Choose xwlazy when you want mapping + policy + audit hooks together, not only the lightest shim. Many tools defer imports only or assume import name == pip name; xwlazy emphasizes table-driven mapping (xwlazy_external_libs.toml + register_import_mapping), optional lockfile/SBOM, PEP 668 defaults, and per-package isolation.

Competitors (honest snapshot): lazy-loader — mature lazy namespace loading, no auto-install. deferred-import — lazy proxy and install-on-demand; per-import package= overrides instead of a shared mapping table. pipimport — old global hook, alpha-era. xwlazy targets operational packaging: curated mappings, scoped enable, deny lists, persist-to-project, optional SBOM/lockfile.

Production safety (defaults): Auditing and lockfile/SBOM writes are off unless you opt in (XWLAZY_AUDIT_ENABLED=1, etc.). Auto-install respects PEP 668 unless explicitly overridden. Prefer allow lists and pre-pinned images for real deployments—see docs/SECURITY.md.

Trust / maturity: The project is beta with a smaller community than mainstream lazy-import helpers—verify behavior in your environment and open issues or PRs if something disagrees with this README or PyPI metadata.

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

Compared to apipkg — apipkg gives a manual export map (lazy attributes → submodules) but not PyPI resolution or installs. xwlazy keeps the mapping table idea and layers import name → pip on the global hook: call register_import_mapping("your_top_level", "distribution>=…") for names missing from xwlazy_external_libs.toml, and use lazy_package_getattr(__name__, {"PublicName": ".submodule"}) as a PEP 562 __getattr__ so first attribute access runs a real import (which the hook can satisfy).

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: skips auto-install when the interpreter is externally managed unless XWLAZY_ALLOW_EXTERNALLY_MANAGED=1 (venv or pre-installed deps remain the usual production approach). 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.
• Distro / system Python: if is_externally_managed() is True, auto-install is skipped by default; use a venv, pip install deps yourself, or set XWLAZY_ALLOW_EXTERNALLY_MANAGED=1 with care.
• 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, docs/REPORT_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: Four layers (0.core, 1.unit, 2.integration, 3.advance). Run:

python tests/runner.py
# or per layer: python tests/0.core/runner.py … python tests/3.advance/runner.py
# full pytest (includes any tests/*.py at repo root): python -m pytest tests -v --tb=short --strict-markers

See docs/REF_51_TEST.md and docs/REPORT_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.82 | Updated: 25-Apr-2026

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