Metadata-Version: 2.4
Name: xwlazy
Version: 1.0.1.73
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: eXonware Backend Team <connect@exonware.com>
License: Apache-2.0
License-File: LICENSE
Keywords: auto-install,automation,dependency-automation,developer-productivity,exonware,import-hook,lazy-import,missing-imports,xwlazy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
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.** 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:** 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` | 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.

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

**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). 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:** 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).
- **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:** 3-layer suite (0.core, 1.unit, 2.integration). Run:

```bash
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](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](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.73 | Updated: 08-Apr-2026

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