Metadata-Version: 2.4
Name: xwlazy
Version: 1.0.1.88
Summary: Convenience wrapper for exonware-xwlazy - provides 'import xwlazy' alias
Project-URL: Homepage, https://exonware.com
Project-URL: Repository, https://github.com/exonware/xwlazy
Project-URL: Documentation, https://github.com/exonware/xwlazy#readme
Project-URL: Subtree, https://github.com/Exonware/XWLazy.git
Author-email: "Eng. Muhammad AlShehri" <connect@exonware.com>
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.8
Requires-Dist: exonware-xwlazy
Provides-Extra: dev
Requires-Dist: exonware-xwlazy[dev]; extra == 'dev'
Provides-Extra: full
Requires-Dist: exonware-xwlazy[full]; extra == 'full'
Provides-Extra: lazy
Requires-Dist: exonware-xwlazy[lazy]; extra == 'lazy'
Provides-Extra: xw
Requires-Dist: exonware-xwlazy[xw]; extra == 'xw'
Description-Content-Type: text/markdown

# ⚡ 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:** connect@exonware.com

[![Status](https://img.shields.io/badge/status-beta-blue.svg)](https://exonware.com)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Automation](https://img.shields.io/badge/automation-missing%20imports%20handled-6f42c1.svg)](https://github.com/exonware/xwlazy)

---

## 📦 Install

**Requires Python 3.8+.** (See [pyproject.toml](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](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](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](https://pypi.org/project/deferred-import/) and legacy [pipimport](https://pypi.org/project/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):**

```python
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`:

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

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

**Global-style helper:**

```python
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](https://github.com/orsinium-labs/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](benchmarks/20260209-benchmark%20competition/README.md#upstream-comparison-deferred-import-vs-xwlazy) (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](benchmarks/20260209-benchmark%20competition/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](https://github.com/scientific-python/lazy_loader) — mature lazy **namespace** loading, **no** auto-install. [deferred-import](https://pypi.org/project/deferred-import/) — lazy proxy **and** install-on-demand; per-import `package=` overrides instead of a shared mapping table. [pipimport](https://pypi.org/project/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](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](https://github.com/exonware/xwlazy/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](https://pypi.org/project/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:**

```python
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](docs/GUIDE_01_USAGE.md)** and **[docs/REF_15_API.md](docs/REF_15_API.md)**.

---

## 📖 Docs and tests

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

- **Start:** [docs/INDEX.md](docs/INDEX.md) - doc index and quick links.
- **Use it:** [docs/GUIDE_01_USAGE.md](docs/GUIDE_01_USAGE.md) - setup, modes, integration, troubleshooting.
- **Requirements and status:** [docs/REF_01_REQ.md](docs/REF_01_REQ.md), [docs/REF_22_PROJECT.md](docs/REF_22_PROJECT.md).
- **API and design:** [docs/REF_15_API.md](docs/REF_15_API.md), [docs/REF_13_ARCH.md](docs/REF_13_ARCH.md).
- **DX and quality:** [docs/REF_14_DX.md](docs/REF_14_DX.md), [docs/REF_50_QA.md](docs/REF_50_QA.md), [docs/REF_54_BENCH.md](docs/REF_54_BENCH.md), [docs/REF_51_TEST.md](docs/REF_51_TEST.md), [docs/REPORT_51_TEST.md](docs/REPORT_51_TEST.md).
- **Ideas and planning:** [docs/REF_12_IDEA.md](docs/REF_12_IDEA.md), [docs/REF_21_PLAN.md](docs/REF_21_PLAN.md).
- **Compliance:** [docs/REF_11_COMP.md](docs/REF_11_COMP.md). **Evidence:** [docs/logs/](docs/logs/) (benchmarks, tests). **Benchmarks:** [benchmarks/INDEX.md](benchmarks/INDEX.md), [docs/logs/benchmarks/](docs/logs/benchmarks/).

**Tests:** Four layers (0.core, 1.unit, 2.integration, 3.advance). Run:

```bash
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](docs/REF_51_TEST.md) and [docs/REPORT_51_TEST.md](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](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

<!-- async-support:start -->
- 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.
<!-- async-support:end -->
Version: 1.0.1.82 | Updated: 25-Apr-2026

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