xwlazy 0.1.0.1__py3-none-any.whl

README.md

@@ -0,0 +1,431 @@
+# xwlazy
+
+**Enterprise-grade lazy loading with automatic dependency installation—the only lazy import library that installs missing packages on-demand while maintaining per-package isolation and security.**
+
+[![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-MIT-green.svg)](LICENSE)
+
+## 🎯 Overview
+
+xwlazy is a production-ready lazy loading system that enables Python packages to automatically install missing dependencies when they're actually used. Unlike traditional dependency management, xwlazy installs dependencies **on-demand** at runtime, reducing initial installation size, avoiding conflicts, and enabling truly optional features.
+
+**Why xwlazy exists:** Traditional dependency management requires installing all dependencies upfront, even if they're never used. This leads to bloated installations, longer setup times, and potential conflicts. xwlazy solves this by installing dependencies only when code actually needs them, while maintaining full security and isolation between packages.
+
+## ✨ Key Features
+
+### 🚀 **Auto-Installation on Demand**
+Dependencies are automatically installed when code first uses them—no manual intervention required. Perfect for optional features that users may never need.
+
+**Why it matters:** Reduces initial installation size by 60-80% for packages with many optional dependencies, while maintaining zero overhead for successful imports.
+
+### 🔒 **Per-Package Isolation**
+Each package (xwsystem, xwnode, xwdata, etc.) can independently enable lazy mode without affecting others. Complete isolation prevents conflicts and enables flexible deployment strategies.
+
+**Why it matters:** Allows mixing lazy and non-lazy packages in the same environment, giving developers full control over which packages use auto-installation.
+
+### 🎯 **Keyword-Based Auto-Detection**
+Packages can opt-in to lazy loading by simply adding `"xwlazy-enabled"` to their `pyproject.toml` keywords—no code changes required.
+
+**Why it matters:** Zero-code integration for package maintainers. Just add a keyword and lazy loading works automatically.
+
+### 🛡️ **Enterprise Security**
+- **Allow/Deny Lists:** Whitelist or blacklist specific packages
+- **SBOM Generation:** Software Bill of Materials for compliance
+- **Vulnerability Auditing:** Automatic security scanning with pip-audit
+- **Lockfile Management:** Track installed packages with versions
+- **PEP 668 Compliance:** Respects externally-managed environments
+
+**Why it matters:** Production environments require security controls. xwlazy provides enterprise-grade security without sacrificing usability.
+
+### ⚡ **Two-Stage Lazy Loading**
+**Stage 1 (Import Time):** Missing imports are logged but don't raise errors—modules load successfully.  
+**Stage 2 (Usage Time):** Dependencies are installed automatically when code first accesses them.
+
+**Why it matters:** Enables clean Python code with standard imports. No defensive `try/except ImportError` blocks needed.
+
+### 📊 **Performance Monitoring**
+Built-in tracking of module load times, access counts, memory usage, and cache hit ratios. Comprehensive statistics API for optimization.
+
+**Why it matters:** Visibility into lazy loading performance helps identify bottlenecks and optimize import strategies.
+
+### 🎨 **Two-Dimensional Mode System**
+
+xwlazy uses a powerful two-dimensional mode system that separates **loading behavior** from **installation behavior**, giving you precise control over how modules are loaded and when packages are installed.
+
+#### **Lazy Load Modes** (When modules load)
+- **NONE:** Standard imports (no lazy loading)
+- **AUTO:** Lazy loading enabled (deferred module loading)
+- **PRELOAD:** Preload all modules on start (parallel loading)
+- **BACKGROUND:** Load modules in background threads (non-blocking)
+- **CACHED:** Cache loaded modules but allow unloading
+
+#### **Lazy Install Modes** (When packages install)
+- **NONE:** No auto-installation
+- **SMART:** Install on first usage (on-demand)
+- **FULL:** Install all dependencies on start (parallel batch)
+- **CLEAN:** Install on usage + uninstall after completion
+- **TEMPORARY:** Always uninstall after use (aggressive cleanup)
+- **SIZE_AWARE:** Install small packages, skip large ones
+- **INTERACTIVE:** Ask user before installing
+- **WARN:** Log warning but don't install (monitoring mode)
+- **DISABLED:** Don't install anything (explicit)
+- **DRY_RUN:** Show what would be installed
+
+#### **Preset Modes** (Quick combinations)
+- **none:** NONE load + NONE install (standard imports)
+- **lite:** AUTO load + NONE install (lazy loading only)
+- **smart:** AUTO load + SMART install (on-demand installation)
+- **full:** AUTO load + FULL install (install all on start)
+- **clean:** AUTO load + CLEAN install (install + cleanup)
+- **temporary:** AUTO load + TEMPORARY install (aggressive cleanup)
+- **size_aware:** AUTO load + SIZE_AWARE install (smart sizing)
+- **auto:** AUTO load + SMART install + auto-uninstall large packages
+
+**Why it matters:** Different environments need different policies. Development might use `smart`, production might use `lite` or `warn`, CI/CD might use `clean` or `temporary`.
+
+## 🏆 Performance Benchmarks
+
+xwlazy has been benchmarked against 8 competing lazy import libraries. **Results show xwlazy is competitive across all load scenarios** while providing significantly more features.
+
+### Latest Benchmark Results (2025-11-17)
+
+| Load Type | xwlazy Time | Rank | vs. Winner | Features |
+|-----------|-------------|------|------------|----------|
+| **Light Load** (1 module) | 2.08 ms | 🥇 **1st** | 2.54x faster | 7 features |
+| **Medium Load** (8 modules) | 6.99 ms | 🥇 **1st** | 8.52x faster | 7 features |
+| **Heavy Load** (22 modules) | 21.13 ms | 🥇 **1st** | 25.75x faster | 7 features |
+| **Enterprise Load** (50+ modules) | 61.28 ms | 🥇 **1st** | 74.66x faster | 7 features |
+
+**Competitive Advantage:** While competitors offer 1-2 features (basic lazy loading), xwlazy provides **7 enterprise features** including auto-installation, security policies, SBOM generation, and per-package isolation.
+
+**See full benchmarks:** [benchmarks/competition_tests/output_log/](benchmarks/competition_tests/output_log/)
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Standard installation
+pip install exonware-xwlazy
+
+# Or install as xwlazy (alias package)
+pip install xwlazy
+```
+
+### Basic Usage
+
+**One-line setup** for per-package lazy loading:
+
+```python
+# In your package's __init__.py
+from xwlazy.lazy import config_package_lazy_install_enabled
+
+# Auto-detects from pip install your-package[lazy]
+config_package_lazy_install_enabled("your-package")
+```
+
+**That's it!** Now use standard imports—missing dependencies install automatically:
+
+```python
+# your-package/serialization/avro.py
+import fastavro  # Auto-installed if missing! ✨
+
+# User code
+from your-package.serialization.avro import AvroSerializer
+serializer = AvroSerializer()  # Installs fastavro on first use
+```
+
+### Keyword-Based Detection (Zero Code)
+
+Add to your `pyproject.toml`:
+
+```toml
+[project]
+name = "my-package"
+keywords = ["xwlazy-enabled"]  # <-- Add this
+```
+
+After `pip install -e .`, xwlazy automatically enables lazy loading for your package—no code changes needed!
+
+## 📖 Documentation
+
+- **[Architecture Reference](docs/REF_ARCH.md)** - System design, patterns, and structure
+- **[Keyword Detection Guide](docs/KEYWORD_DETECTION.md)** - Zero-code integration
+- **[Competition Benchmarks](benchmarks/competition_tests/)** - Performance comparisons
+- **[Performance Analysis](benchmarks/competition_tests/PERFORMANCE_ANALYSIS.md)** - Optimization recommendations
+
+## 💡 Use Cases
+
+### 1. Optional Format Support
+
+```python
+# xwsystem/serialization/avro.py
+import fastavro  # Only installed if user needs Avro support
+
+class AvroSerializer:
+    def serialize(self, data):
+        return fastavro.schemaless_writer(...)
+```
+
+**Benefit:** Users who never use Avro don't install fastavro, reducing installation size.
+
+### 2. Development Tools
+
+```python
+# xwnode/visualization/graphviz.py
+import graphviz  # Only installed in development
+
+def visualize_graph(node):
+    return graphviz.render(...)
+```
+
+**Benefit:** Production deployments don't include development-only dependencies.
+
+### 3. Platform-Specific Features
+
+```python
+# xwdata/formats/excel.py
+try:
+    import openpyxl  # Windows/Linux
+except ImportError:
+    import xlrd  # macOS fallback
+```
+
+**Benefit:** Platform-specific dependencies install automatically based on availability.
+
+### 4. Security-Controlled Environments
+
+```python
+from xwlazy.lazy import (
+    config_package_lazy_install_enabled,
+    set_package_allow_list,
+)
+
+# Only allow specific packages
+config_package_lazy_install_enabled("xwsystem")
+set_package_allow_list("xwsystem", ["fastavro", "protobuf", "msgpack"])
+
+# Attempts to install other packages are blocked
+import suspicious_package  # ❌ Blocked by security policy
+```
+
+**Benefit:** Enterprise environments can restrict auto-installation to approved packages only.
+
+## 🔧 Advanced Configuration
+
+### Two-Dimensional Mode Configuration
+
+#### Using Preset Modes (Recommended)
+
+```python
+from xwlazy.lazy import config_package_lazy_install_enabled
+
+# Quick preset modes
+config_package_lazy_install_enabled("xwsystem", enabled=True, mode="smart")   # On-demand install
+config_package_lazy_install_enabled("xwsystem", enabled=True, mode="full")   # Install all on start
+config_package_lazy_install_enabled("xwsystem", enabled=True, mode="clean") # Install + cleanup
+config_package_lazy_install_enabled("xwsystem", enabled=True, mode="lite")   # Lazy load only
+```
+
+#### Using Explicit Mode Configuration
+
+```python
+from xwlazy.lazy import (
+    config_package_lazy_install_enabled,
+    LazyLoadMode,
+    LazyInstallMode,
+    LazyModeConfig,
+)
+
+# Explicit two-dimensional configuration
+config_package_lazy_install_enabled(
+    "xwsystem",
+    enabled=True,
+    load_mode=LazyLoadMode.PRELOAD,      # Preload all modules
+    install_mode=LazyInstallMode.SMART   # Install on-demand
+)
+
+# Or use LazyModeConfig for full control
+config = LazyModeConfig(
+    load_mode=LazyLoadMode.BACKGROUND,
+    install_mode=LazyInstallMode.SIZE_AWARE,
+    large_package_threshold_mb=100.0,  # Skip packages > 100MB
+    background_workers=4              # 4 background workers
+)
+config_package_lazy_install_enabled(
+    "xwsystem",
+    enabled=True,
+    mode_config=config
+)
+```
+
+#### Using exonware.conf (Global Configuration)
+
+```python
+import exonware.conf as conf
+
+# Set global lazy mode for all packages
+conf.lazy = "smart"   # or "lite", "full", "clean", "auto", etc.
+```
+
+#### Special Purpose Modes
+
+```python
+# Interactive mode: Ask user before installing
+config_package_lazy_install_enabled(
+    "xwsystem",
+    enabled=True,
+    mode="interactive"  # or LazyInstallMode.INTERACTIVE
+)
+
+# Warn mode: Log but don't install (monitoring)
+config_package_lazy_install_enabled(
+    "xwsystem",
+    enabled=True,
+    mode="warn"  # or LazyInstallMode.WARN
+)
+```
+
+### Security Policies
+
+```python
+from xwlazy.lazy import (
+    set_package_allow_list,
+    set_package_deny_list,
+    set_package_lockfile,
+)
+
+# Whitelist approach
+set_package_allow_list("xwsystem", ["fastavro", "protobuf"])
+
+# Blacklist approach
+set_package_deny_list("xwsystem", ["suspicious-package"])
+
+# Track installations
+set_package_lockfile("xwsystem", "xwsystem-lazy-lock.json")
+```
+
+### SBOM Generation
+
+```python
+from xwlazy.lazy import generate_package_sbom
+
+# Generate Software Bill of Materials for compliance
+sbom = generate_package_sbom("xwsystem", "xwsystem-sbom.json")
+```
+
+### Statistics and Monitoring
+
+```python
+from xwlazy.lazy import get_lazy_install_stats
+
+# Get installation statistics
+stats = get_lazy_install_stats("xwsystem")
+# {
+#   'enabled': True,
+#   'mode': 'auto',
+#   'installed_packages': ['fastavro', 'protobuf'],
+#   'failed_packages': [],
+#   'total_installed': 2
+# }
+```
+
+## 🎨 Design Patterns
+
+xwlazy implements 8 design patterns for maintainability and extensibility:
+
+1. **Facade Pattern** - Unified API to complex subsystems
+2. **Strategy Pattern** - Pluggable discovery/installation strategies
+3. **Template Method** - Base classes define common workflows
+4. **Singleton** - Global instances for system-wide state
+5. **Registry** - Per-package isolation and management
+6. **Observer** - Performance monitoring and tracking
+7. **Proxy** - Deferred loading and lazy access
+8. **Factory** - Creating appropriate handlers by context
+
+## 🔒 Security Considerations
+
+### PEP 668 Compliance
+xwlazy respects externally-managed Python environments and refuses to install in system Python, suggesting virtual environments instead.
+
+### System Module Protection
+Built-in modules (stdlib) are never auto-installed, preventing accidental system modifications.
+
+### Vulnerability Scanning
+Optional pip-audit integration scans packages after installation and logs security warnings.
+
+### Custom PyPI Mirrors
+Support for internal PyPI servers with custom index URLs and trusted hosts.
+
+## ⚡ Performance Characteristics
+
+- **Zero overhead** for successful imports (hooks only trigger on failures)
+- **Aggressive caching** with file modification time checks
+- **Lazy initialization** - everything loads only when needed
+- **Thread-safe** operations with proper locking
+- **Import overhead:** ~0.1ms for successful imports
+- **First failure:** ~50ms (discovery + policy check)
+- **Subsequent failures:** ~5ms (cached discovery)
+
+## 🧪 Testing
+
+xwlazy includes comprehensive test suites:
+
+```bash
+# Run all tests
+python tests/runner.py
+
+# Run specific test layers
+python tests/0.core/runner.py      # Core tests (< 30s)
+python tests/1.unit/runner.py     # Unit tests (< 5m)
+```
+
+## 📊 Comparison with Competitors
+
+| Feature | xwlazy | lazy-imports-lite | lazy-loader | lazy_import |
+|---------|--------|-------------------|-------------|-------------|
+| **Lazy Import** | ✅ | ✅ | ✅ | ✅ |
+| **Auto-Installation** | ✅ | ❌ | ❌ | ❌ |
+| **Keyword Detection** | ✅ | ✅ | ❌ | ❌ |
+| **Per-Package Isolation** | ✅ | ❌ | ❌ | ❌ |
+| **Security Policies** | ✅ | ❌ | ❌ | ❌ |
+| **SBOM Generation** | ✅ | ❌ | ❌ | ❌ |
+| **Performance Monitoring** | ✅ | ❌ | ❌ | ❌ |
+| **Two-Stage Loading** | ✅ | ❌ | ❌ | ❌ |
+| **Total Features** | **7** | **2** | **1** | **1** |
+
+## 🤝 Contributing
+
+xwlazy is part of the eXonware ecosystem. For contributions, please follow:
+
+- [Development Guide](../../docs/guides/GUIDE_DEV.md) - Core development standards
+- [Testing Guide](../../docs/guides/GUIDE_TEST.md) - Testing standards
+- [Documentation Guide](../../docs/guides/GUIDE_DOCS.md) - Documentation standards
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🔗 Links
+
+- **Homepage:** https://exonware.com
+- **Repository:** https://github.com/exonware/xwlazy
+- **Email:** connect@exonware.com
+- **Author:** Eng. Muhammad AlShehri
+
+## 🙏 Acknowledgments
+
+xwlazy is built with inspiration from the Python lazy import ecosystem, particularly:
+- `lazy-imports-lite` for keyword-based detection concept
+- `lazy-loader` for scientific Python patterns
+- The broader Python import system for hook mechanisms
+
+---
+
+**Part of the eXonware ecosystem** - Enterprise-grade Python libraries for modern software development.
+
+*Last Updated: 17-Nov-2025*
+
+> **Note:** For the current version, use `from exonware.xwlazy import __version__` or `import exonware.xwlazy; print(exonware.xwlazy.__version__)`
+

src/xwlazy_wrapper.py

@@ -0,0 +1,20 @@
+"""
+xwlazy Wrapper Package
+
+This is a convenience wrapper that provides 'import xwlazy' functionality.
+The actual implementation is in the exonware-xwlazy package.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Generation Date: 10-Oct-2025
+"""
+
+# This wrapper package depends on exonware-xwlazy
+# When you pip install xwlazy, it automatically installs exonware-xwlazy
+# Both import paths then work:
+#   - import xwlazy
+#   - import exonware.xwlazy
+
+__all__ = []
+

xwlazy-0.1.0.1.dist-info/METADATA

@@ -0,0 +1,454 @@
+Metadata-Version: 2.4
+Name: xwlazy
+Version: 0.1.0.1
+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: MIT
+License-File: LICENSE
+Keywords: exonware,lazy,xwlazy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: exonware-xwlazy
+Description-Content-Type: text/markdown
+
+# xwlazy
+
+**Enterprise-grade lazy loading with automatic dependency installation—the only lazy import library that installs missing packages on-demand while maintaining per-package isolation and security.**
+
+[![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-MIT-green.svg)](LICENSE)
+
+## 🎯 Overview
+
+xwlazy is a production-ready lazy loading system that enables Python packages to automatically install missing dependencies when they're actually used. Unlike traditional dependency management, xwlazy installs dependencies **on-demand** at runtime, reducing initial installation size, avoiding conflicts, and enabling truly optional features.
+
+**Why xwlazy exists:** Traditional dependency management requires installing all dependencies upfront, even if they're never used. This leads to bloated installations, longer setup times, and potential conflicts. xwlazy solves this by installing dependencies only when code actually needs them, while maintaining full security and isolation between packages.
+
+## ✨ Key Features
+
+### 🚀 **Auto-Installation on Demand**
+Dependencies are automatically installed when code first uses them—no manual intervention required. Perfect for optional features that users may never need.
+
+**Why it matters:** Reduces initial installation size by 60-80% for packages with many optional dependencies, while maintaining zero overhead for successful imports.
+
+### 🔒 **Per-Package Isolation**
+Each package (xwsystem, xwnode, xwdata, etc.) can independently enable lazy mode without affecting others. Complete isolation prevents conflicts and enables flexible deployment strategies.
+
+**Why it matters:** Allows mixing lazy and non-lazy packages in the same environment, giving developers full control over which packages use auto-installation.
+
+### 🎯 **Keyword-Based Auto-Detection**
+Packages can opt-in to lazy loading by simply adding `"xwlazy-enabled"` to their `pyproject.toml` keywords—no code changes required.
+
+**Why it matters:** Zero-code integration for package maintainers. Just add a keyword and lazy loading works automatically.
+
+### 🛡️ **Enterprise Security**
+- **Allow/Deny Lists:** Whitelist or blacklist specific packages
+- **SBOM Generation:** Software Bill of Materials for compliance
+- **Vulnerability Auditing:** Automatic security scanning with pip-audit
+- **Lockfile Management:** Track installed packages with versions
+- **PEP 668 Compliance:** Respects externally-managed environments
+
+**Why it matters:** Production environments require security controls. xwlazy provides enterprise-grade security without sacrificing usability.
+
+### ⚡ **Two-Stage Lazy Loading**
+**Stage 1 (Import Time):** Missing imports are logged but don't raise errors—modules load successfully.  
+**Stage 2 (Usage Time):** Dependencies are installed automatically when code first accesses them.
+
+**Why it matters:** Enables clean Python code with standard imports. No defensive `try/except ImportError` blocks needed.
+
+### 📊 **Performance Monitoring**
+Built-in tracking of module load times, access counts, memory usage, and cache hit ratios. Comprehensive statistics API for optimization.
+
+**Why it matters:** Visibility into lazy loading performance helps identify bottlenecks and optimize import strategies.
+
+### 🎨 **Two-Dimensional Mode System**
+
+xwlazy uses a powerful two-dimensional mode system that separates **loading behavior** from **installation behavior**, giving you precise control over how modules are loaded and when packages are installed.
+
+#### **Lazy Load Modes** (When modules load)
+- **NONE:** Standard imports (no lazy loading)
+- **AUTO:** Lazy loading enabled (deferred module loading)
+- **PRELOAD:** Preload all modules on start (parallel loading)
+- **BACKGROUND:** Load modules in background threads (non-blocking)
+- **CACHED:** Cache loaded modules but allow unloading
+
+#### **Lazy Install Modes** (When packages install)
+- **NONE:** No auto-installation
+- **SMART:** Install on first usage (on-demand)
+- **FULL:** Install all dependencies on start (parallel batch)
+- **CLEAN:** Install on usage + uninstall after completion
+- **TEMPORARY:** Always uninstall after use (aggressive cleanup)
+- **SIZE_AWARE:** Install small packages, skip large ones
+- **INTERACTIVE:** Ask user before installing
+- **WARN:** Log warning but don't install (monitoring mode)
+- **DISABLED:** Don't install anything (explicit)
+- **DRY_RUN:** Show what would be installed
+
+#### **Preset Modes** (Quick combinations)
+- **none:** NONE load + NONE install (standard imports)
+- **lite:** AUTO load + NONE install (lazy loading only)
+- **smart:** AUTO load + SMART install (on-demand installation)
+- **full:** AUTO load + FULL install (install all on start)
+- **clean:** AUTO load + CLEAN install (install + cleanup)
+- **temporary:** AUTO load + TEMPORARY install (aggressive cleanup)
+- **size_aware:** AUTO load + SIZE_AWARE install (smart sizing)
+- **auto:** AUTO load + SMART install + auto-uninstall large packages
+
+**Why it matters:** Different environments need different policies. Development might use `smart`, production might use `lite` or `warn`, CI/CD might use `clean` or `temporary`.
+
+## 🏆 Performance Benchmarks
+
+xwlazy has been benchmarked against 8 competing lazy import libraries. **Results show xwlazy is competitive across all load scenarios** while providing significantly more features.
+
+### Latest Benchmark Results (2025-11-17)
+
+| Load Type | xwlazy Time | Rank | vs. Winner | Features |
+|-----------|-------------|------|------------|----------|
+| **Light Load** (1 module) | 2.08 ms | 🥇 **1st** | 2.54x faster | 7 features |
+| **Medium Load** (8 modules) | 6.99 ms | 🥇 **1st** | 8.52x faster | 7 features |
+| **Heavy Load** (22 modules) | 21.13 ms | 🥇 **1st** | 25.75x faster | 7 features |
+| **Enterprise Load** (50+ modules) | 61.28 ms | 🥇 **1st** | 74.66x faster | 7 features |
+
+**Competitive Advantage:** While competitors offer 1-2 features (basic lazy loading), xwlazy provides **7 enterprise features** including auto-installation, security policies, SBOM generation, and per-package isolation.
+
+**See full benchmarks:** [benchmarks/competition_tests/output_log/](benchmarks/competition_tests/output_log/)
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Standard installation
+pip install exonware-xwlazy
+
+# Or install as xwlazy (alias package)
+pip install xwlazy
+```
+
+### Basic Usage
+
+**One-line setup** for per-package lazy loading:
+
+```python
+# In your package's __init__.py
+from xwlazy.lazy import config_package_lazy_install_enabled
+
+# Auto-detects from pip install your-package[lazy]
+config_package_lazy_install_enabled("your-package")
+```
+
+**That's it!** Now use standard imports—missing dependencies install automatically:
+
+```python
+# your-package/serialization/avro.py
+import fastavro  # Auto-installed if missing! ✨
+
+# User code
+from your-package.serialization.avro import AvroSerializer
+serializer = AvroSerializer()  # Installs fastavro on first use
+```
+
+### Keyword-Based Detection (Zero Code)
+
+Add to your `pyproject.toml`:
+
+```toml
+[project]
+name = "my-package"
+keywords = ["xwlazy-enabled"]  # <-- Add this
+```
+
+After `pip install -e .`, xwlazy automatically enables lazy loading for your package—no code changes needed!
+
+## 📖 Documentation
+
+- **[Architecture Reference](docs/REF_ARCH.md)** - System design, patterns, and structure
+- **[Keyword Detection Guide](docs/KEYWORD_DETECTION.md)** - Zero-code integration
+- **[Competition Benchmarks](benchmarks/competition_tests/)** - Performance comparisons
+- **[Performance Analysis](benchmarks/competition_tests/PERFORMANCE_ANALYSIS.md)** - Optimization recommendations
+
+## 💡 Use Cases
+
+### 1. Optional Format Support
+
+```python
+# xwsystem/serialization/avro.py
+import fastavro  # Only installed if user needs Avro support
+
+class AvroSerializer:
+    def serialize(self, data):
+        return fastavro.schemaless_writer(...)
+```
+
+**Benefit:** Users who never use Avro don't install fastavro, reducing installation size.
+
+### 2. Development Tools
+
+```python
+# xwnode/visualization/graphviz.py
+import graphviz  # Only installed in development
+
+def visualize_graph(node):
+    return graphviz.render(...)
+```
+
+**Benefit:** Production deployments don't include development-only dependencies.
+
+### 3. Platform-Specific Features
+
+```python
+# xwdata/formats/excel.py
+try:
+    import openpyxl  # Windows/Linux
+except ImportError:
+    import xlrd  # macOS fallback
+```
+
+**Benefit:** Platform-specific dependencies install automatically based on availability.
+
+### 4. Security-Controlled Environments
+
+```python
+from xwlazy.lazy import (
+    config_package_lazy_install_enabled,
+    set_package_allow_list,
+)
+
+# Only allow specific packages
+config_package_lazy_install_enabled("xwsystem")
+set_package_allow_list("xwsystem", ["fastavro", "protobuf", "msgpack"])
+
+# Attempts to install other packages are blocked
+import suspicious_package  # ❌ Blocked by security policy
+```
+
+**Benefit:** Enterprise environments can restrict auto-installation to approved packages only.
+
+## 🔧 Advanced Configuration
+
+### Two-Dimensional Mode Configuration
+
+#### Using Preset Modes (Recommended)
+
+```python
+from xwlazy.lazy import config_package_lazy_install_enabled
+
+# Quick preset modes
+config_package_lazy_install_enabled("xwsystem", enabled=True, mode="smart")   # On-demand install
+config_package_lazy_install_enabled("xwsystem", enabled=True, mode="full")   # Install all on start
+config_package_lazy_install_enabled("xwsystem", enabled=True, mode="clean") # Install + cleanup
+config_package_lazy_install_enabled("xwsystem", enabled=True, mode="lite")   # Lazy load only
+```
+
+#### Using Explicit Mode Configuration
+
+```python
+from xwlazy.lazy import (
+    config_package_lazy_install_enabled,
+    LazyLoadMode,
+    LazyInstallMode,
+    LazyModeConfig,
+)
+
+# Explicit two-dimensional configuration
+config_package_lazy_install_enabled(
+    "xwsystem",
+    enabled=True,
+    load_mode=LazyLoadMode.PRELOAD,      # Preload all modules
+    install_mode=LazyInstallMode.SMART   # Install on-demand
+)
+
+# Or use LazyModeConfig for full control
+config = LazyModeConfig(
+    load_mode=LazyLoadMode.BACKGROUND,
+    install_mode=LazyInstallMode.SIZE_AWARE,
+    large_package_threshold_mb=100.0,  # Skip packages > 100MB
+    background_workers=4              # 4 background workers
+)
+config_package_lazy_install_enabled(
+    "xwsystem",
+    enabled=True,
+    mode_config=config
+)
+```
+
+#### Using exonware.conf (Global Configuration)
+
+```python
+import exonware.conf as conf
+
+# Set global lazy mode for all packages
+conf.lazy = "smart"   # or "lite", "full", "clean", "auto", etc.
+```
+
+#### Special Purpose Modes
+
+```python
+# Interactive mode: Ask user before installing
+config_package_lazy_install_enabled(
+    "xwsystem",
+    enabled=True,
+    mode="interactive"  # or LazyInstallMode.INTERACTIVE
+)
+
+# Warn mode: Log but don't install (monitoring)
+config_package_lazy_install_enabled(
+    "xwsystem",
+    enabled=True,
+    mode="warn"  # or LazyInstallMode.WARN
+)
+```
+
+### Security Policies
+
+```python
+from xwlazy.lazy import (
+    set_package_allow_list,
+    set_package_deny_list,
+    set_package_lockfile,
+)
+
+# Whitelist approach
+set_package_allow_list("xwsystem", ["fastavro", "protobuf"])
+
+# Blacklist approach
+set_package_deny_list("xwsystem", ["suspicious-package"])
+
+# Track installations
+set_package_lockfile("xwsystem", "xwsystem-lazy-lock.json")
+```
+
+### SBOM Generation
+
+```python
+from xwlazy.lazy import generate_package_sbom
+
+# Generate Software Bill of Materials for compliance
+sbom = generate_package_sbom("xwsystem", "xwsystem-sbom.json")
+```
+
+### Statistics and Monitoring
+
+```python
+from xwlazy.lazy import get_lazy_install_stats
+
+# Get installation statistics
+stats = get_lazy_install_stats("xwsystem")
+# {
+#   'enabled': True,
+#   'mode': 'auto',
+#   'installed_packages': ['fastavro', 'protobuf'],
+#   'failed_packages': [],
+#   'total_installed': 2
+# }
+```
+
+## 🎨 Design Patterns
+
+xwlazy implements 8 design patterns for maintainability and extensibility:
+
+1. **Facade Pattern** - Unified API to complex subsystems
+2. **Strategy Pattern** - Pluggable discovery/installation strategies
+3. **Template Method** - Base classes define common workflows
+4. **Singleton** - Global instances for system-wide state
+5. **Registry** - Per-package isolation and management
+6. **Observer** - Performance monitoring and tracking
+7. **Proxy** - Deferred loading and lazy access
+8. **Factory** - Creating appropriate handlers by context
+
+## 🔒 Security Considerations
+
+### PEP 668 Compliance
+xwlazy respects externally-managed Python environments and refuses to install in system Python, suggesting virtual environments instead.
+
+### System Module Protection
+Built-in modules (stdlib) are never auto-installed, preventing accidental system modifications.
+
+### Vulnerability Scanning
+Optional pip-audit integration scans packages after installation and logs security warnings.
+
+### Custom PyPI Mirrors
+Support for internal PyPI servers with custom index URLs and trusted hosts.
+
+## ⚡ Performance Characteristics
+
+- **Zero overhead** for successful imports (hooks only trigger on failures)
+- **Aggressive caching** with file modification time checks
+- **Lazy initialization** - everything loads only when needed
+- **Thread-safe** operations with proper locking
+- **Import overhead:** ~0.1ms for successful imports
+- **First failure:** ~50ms (discovery + policy check)
+- **Subsequent failures:** ~5ms (cached discovery)
+
+## 🧪 Testing
+
+xwlazy includes comprehensive test suites:
+
+```bash
+# Run all tests
+python tests/runner.py
+
+# Run specific test layers
+python tests/0.core/runner.py      # Core tests (< 30s)
+python tests/1.unit/runner.py     # Unit tests (< 5m)
+```
+
+## 📊 Comparison with Competitors
+
+| Feature | xwlazy | lazy-imports-lite | lazy-loader | lazy_import |
+|---------|--------|-------------------|-------------|-------------|
+| **Lazy Import** | ✅ | ✅ | ✅ | ✅ |
+| **Auto-Installation** | ✅ | ❌ | ❌ | ❌ |
+| **Keyword Detection** | ✅ | ✅ | ❌ | ❌ |
+| **Per-Package Isolation** | ✅ | ❌ | ❌ | ❌ |
+| **Security Policies** | ✅ | ❌ | ❌ | ❌ |
+| **SBOM Generation** | ✅ | ❌ | ❌ | ❌ |
+| **Performance Monitoring** | ✅ | ❌ | ❌ | ❌ |
+| **Two-Stage Loading** | ✅ | ❌ | ❌ | ❌ |
+| **Total Features** | **7** | **2** | **1** | **1** |
+
+## 🤝 Contributing
+
+xwlazy is part of the eXonware ecosystem. For contributions, please follow:
+
+- [Development Guide](../../docs/guides/GUIDE_DEV.md) - Core development standards
+- [Testing Guide](../../docs/guides/GUIDE_TEST.md) - Testing standards
+- [Documentation Guide](../../docs/guides/GUIDE_DOCS.md) - Documentation standards
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🔗 Links
+
+- **Homepage:** https://exonware.com
+- **Repository:** https://github.com/exonware/xwlazy
+- **Email:** connect@exonware.com
+- **Author:** Eng. Muhammad AlShehri
+
+## 🙏 Acknowledgments
+
+xwlazy is built with inspiration from the Python lazy import ecosystem, particularly:
+- `lazy-imports-lite` for keyword-based detection concept
+- `lazy-loader` for scientific Python patterns
+- The broader Python import system for hook mechanisms
+
+---
+
+**Part of the eXonware ecosystem** - Enterprise-grade Python libraries for modern software development.
+
+*Last Updated: 17-Nov-2025*
+
+> **Note:** For the current version, use `from exonware.xwlazy import __version__` or `import exonware.xwlazy; print(exonware.xwlazy.__version__)`
+

xwlazy-0.1.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+README.md,sha256=_TPNldwgooH5cGTNpt1GFAQTtrYM5yS-AFc0fy1VfdE,15672
+src/xwlazy_wrapper.py,sha256=qYc2lJ5WZdSxgBhHrEUC39KHSmWl5YGqirw_ro4WhpE,498
+xwlazy-0.1.0.1.dist-info/METADATA,sha256=57uPbcauFmQb-yYD0pwp2COgB7mObxDP2UYQJ7AxPXg,16622
+xwlazy-0.1.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+xwlazy-0.1.0.1.dist-info/licenses/LICENSE,sha256=w42ohoEUfhyT0NgiivAL4fWg2AMRLGnfXPMAR4EO-MU,1094
+xwlazy-0.1.0.1.dist-info/RECORD,,

xwlazy-0.1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

xwlazy-0.1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 eXonware.com - Eng. Muhammad AlShehri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.