pico-ioc 1.5.0__tar.gz → 2.0.0__tar.gz

{pico_ioc-1.5.0 → pico_ioc-2.0.0}/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.10", "3.11", "3.12", "3.13" ]
+        python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]
 
     steps:
       - name: Checkout

pico_ioc-2.0.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 2.0.0
+Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Pérez Cabrera
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Repository, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-ioc/issues
+Keywords: ioc,di,dependency injection,inversion of control,decorator
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 📦 Pico-IoC: A Robust, Async-Native IoC Container for Python
+
+[![PyPI](https://img.shields.io/pypi/v/pico-ioc.svg)](https://pypi.org/project/pico-ioc/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-ioc)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-ioc/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-ioc/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-ioc)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+
+**pico-ioc** is a **robust, async-native, decorator-based IoC container for Python**.
+It helps you build loosely-coupled, testable, enterprise-grade applications without manual wiring. Inspired by the Spring ecosystem, but fully Pythonic.
+
+> ⚠️ **Requires Python 3.10+** (due to extensive use of modern `typing` features).
+
+---
+
+## ⚖️ Principles
+
+* **Focus & Simplicity**: A declarative API for one job: managing dependencies. It avoids accidental complexity by doing one thing well.
+* **Declarative & Explicit**: No magic. Behavior is deterministic, relying on explicit decorators (`@component`, `@factory`) and type hints.
+* **Unified Composition Root**: The application is assembled from a single entry point (`init`) which defines a clear, predictable boundary.
+* **Fail-Fast by Design**: Catches **circular dependencies** and **missing bindings** at startup, not at runtime. If the application runs, it's wired correctly.
+* **Testability First**: Features like `@conditional`, profiles, and `overrides` are first-class citizens, enabling fast and isolated testing.
+* **Async Native & Extensible**: Full `async`/`await` support, AOP (`@intercepted_by`), and a built-in `EventBus` are available out-of-the-box.
+* **Framework Agnostic**: Zero hard dependencies (standard library only). It works with any Python application, from simple scripts to complex web servers.
+
+---
+
+## ✨ Why Pico-IoC?
+
+`pico-ioc` exists to solve a common problem that arises as Python applications grow: managing how objects are created and connected becomes complex and brittle. This manual wiring, where a change deep in the application can cause a cascade of updates, makes the code hard to test and maintain.
+
+`pico-ioc` introduces the principle of Inversion of Control (IoC) in a simple, Pythonic way. Instead of you creating and connecting every object, you declare your components with a simple `@component` decorator, and the container automatically wires them together based on their type hints. It brings the architectural robustness and testability of mature frameworks like Spring to the Python ecosystem, allowing you to build complex, loosely-coupled applications that remain simple to manage.
+
+| Feature | Manual Wiring | With Pico-IoC |
+| :--- | :--- | :--- |
+| **Object Creation** | `service = Service(Repo(Config()))` | `svc = container.get(Service)` |
+| **Testing** | Manual replacement or monkey-patching | `overrides={Repo: FakeRepo()}` |
+| **Coupling** | High (code knows about constructors) | Low (code just asks for a type) |
+| **Maintenance** | Brittle (changing a constructor breaks consumers) | Robust (changes are isolated) |
+| **Learning Curve** | Ad-hoc, implicit patterns | Uniform, explicit, documented |
+
+---
+
+## 🧩 Features
+
+### Core
+
+* **Zero external dependencies** — pure Python, framework-agnostic.
+* **Decorator-based API** — `@component`, `@factory`, `@provides`, `@configuration`.
+* **Fail-fast Bootstrap** — Detects **circular dependencies** and **missing bindings** at startup.
+* **Async-Native Resolution** — Full `async`/`await` support with `container.aget()`.
+* **Sophisticated Scopes** — `singleton`, `prototype`, and `ContextVar`-based scopes (e.g., `request`, `session`).
+* **Typed Configuration** — Injects `dataclasses` from environment/files via `@configuration`.
+* **Test-Driven** — Built-in `overrides` and `profiles` for easy mocking.
+
+### Advanced
+
+* **AOP / Interceptors** — Intercept method calls with `@intercepted_by`.
+* **Qualifiers** — Inject subsets of components with `Annotated[List[T], Qualifier(...)]`.
+* **Async Event Bus** — Built-in `EventBus` for decoupled, event-driven architecture.
+* **Conditional Registration** — `@conditional` (by profile, env var) and `@on_missing` (fallbacks).
+* **Lifecycle Hooks** — `@configure` (post-init) and `@cleanup` (on shutdown).
+* **Health Checks** — Built-in `@health` decorator and `container.health_check()`.
+* **Serializable Proxies** — Lazy (`@lazy`) and AOP proxies are `pickle`-safe.
+
+---
+
+## 📦 Installation
+
+```bash
+# Requires Python 3.10+
+pip install pico-ioc
+````
+
+-----
+
+## 🚀 Quick Start
+
+```python
+from pico_ioc import component, init, configuration
+from dataclasses import dataclass
+
+@configuration
+@dataclass
+class Config:
+    url: str = "sqlite:///demo.db"
+
+@component
+class Repo:
+    def __init__(self, cfg: Config):
+        self.url = cfg.url
+    def fetch(self): 
+        return f"fetching from {self.url}"
+
+@component
+class Service:
+    def __init__(self, repo: Repo):
+        self.repo = repo
+    def run(self): 
+        return self.repo.fetch()
+
+# Bootstrap the container by scanning modules
+# We use __name__ to scan the current module
+container = init(modules=[__name__])
+
+# Resolve the service and run
+svc = container.get(Service)
+print(svc.run())
+```
+
+**Output:**
+
+```
+fetching from sqlite:///demo.db
+```
+
+-----
+
+### Quick Overrides for Testing
+
+The `init` function accepts `overrides` to replace any component for testing.
+
+```python
+import my_app_module
+from pico_ioc import init
+
+# Define a fake repository
+class FakeRepo:
+    def fetch(self): 
+        return "fake-data"
+
+# Initialize the container, overriding the real Repo
+container = init(
+    modules=[my_app_module],
+    overrides={
+        Repo: FakeRepo()  # Override by type
+    }
+)
+
+# The service now receives FakeRepo instead of the real one
+svc = container.get(Service)
+assert svc.run() == "fake-data"
+```
+
+-----
+
+## 📖 Documentation
+
+  * **🚀 New to pico-ioc? Start with the User Guide.**
+
+      * [**guide.md**](.docs/guide.md) — Learn with practical examples: testing, configuration, AOP, async, and web framework integration.
+
+  * **🏗️ Want to understand the internals? See the Architecture.**
+
+      * [**architecture.md**](./docs/architecture.md) — A deep dive into the resolution algorithm, lifecycle, and internal design.
+
+-----
+
+## 🧪 Development
+
+```bash
+pip install tox
+tox
+```
+
+-----
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+-----
+
+## 📜 License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
+
+```
+```
+
+

pico_ioc-2.0.0/README.md

@@ -0,0 +1,184 @@
+# 📦 Pico-IoC: A Robust, Async-Native IoC Container for Python
+
+[![PyPI](https://img.shields.io/pypi/v/pico-ioc.svg)](https://pypi.org/project/pico-ioc/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-ioc)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-ioc/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-ioc/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-ioc)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+
+**pico-ioc** is a **robust, async-native, decorator-based IoC container for Python**.
+It helps you build loosely-coupled, testable, enterprise-grade applications without manual wiring. Inspired by the Spring ecosystem, but fully Pythonic.
+
+> ⚠️ **Requires Python 3.10+** (due to extensive use of modern `typing` features).
+
+---
+
+## ⚖️ Principles
+
+* **Focus & Simplicity**: A declarative API for one job: managing dependencies. It avoids accidental complexity by doing one thing well.
+* **Declarative & Explicit**: No magic. Behavior is deterministic, relying on explicit decorators (`@component`, `@factory`) and type hints.
+* **Unified Composition Root**: The application is assembled from a single entry point (`init`) which defines a clear, predictable boundary.
+* **Fail-Fast by Design**: Catches **circular dependencies** and **missing bindings** at startup, not at runtime. If the application runs, it's wired correctly.
+* **Testability First**: Features like `@conditional`, profiles, and `overrides` are first-class citizens, enabling fast and isolated testing.
+* **Async Native & Extensible**: Full `async`/`await` support, AOP (`@intercepted_by`), and a built-in `EventBus` are available out-of-the-box.
+* **Framework Agnostic**: Zero hard dependencies (standard library only). It works with any Python application, from simple scripts to complex web servers.
+
+---
+
+## ✨ Why Pico-IoC?
+
+`pico-ioc` exists to solve a common problem that arises as Python applications grow: managing how objects are created and connected becomes complex and brittle. This manual wiring, where a change deep in the application can cause a cascade of updates, makes the code hard to test and maintain.
+
+`pico-ioc` introduces the principle of Inversion of Control (IoC) in a simple, Pythonic way. Instead of you creating and connecting every object, you declare your components with a simple `@component` decorator, and the container automatically wires them together based on their type hints. It brings the architectural robustness and testability of mature frameworks like Spring to the Python ecosystem, allowing you to build complex, loosely-coupled applications that remain simple to manage.
+
+| Feature | Manual Wiring | With Pico-IoC |
+| :--- | :--- | :--- |
+| **Object Creation** | `service = Service(Repo(Config()))` | `svc = container.get(Service)` |
+| **Testing** | Manual replacement or monkey-patching | `overrides={Repo: FakeRepo()}` |
+| **Coupling** | High (code knows about constructors) | Low (code just asks for a type) |
+| **Maintenance** | Brittle (changing a constructor breaks consumers) | Robust (changes are isolated) |
+| **Learning Curve** | Ad-hoc, implicit patterns | Uniform, explicit, documented |
+
+---
+
+## 🧩 Features
+
+### Core
+
+* **Zero external dependencies** — pure Python, framework-agnostic.
+* **Decorator-based API** — `@component`, `@factory`, `@provides`, `@configuration`.
+* **Fail-fast Bootstrap** — Detects **circular dependencies** and **missing bindings** at startup.
+* **Async-Native Resolution** — Full `async`/`await` support with `container.aget()`.
+* **Sophisticated Scopes** — `singleton`, `prototype`, and `ContextVar`-based scopes (e.g., `request`, `session`).
+* **Typed Configuration** — Injects `dataclasses` from environment/files via `@configuration`.
+* **Test-Driven** — Built-in `overrides` and `profiles` for easy mocking.
+
+### Advanced
+
+* **AOP / Interceptors** — Intercept method calls with `@intercepted_by`.
+* **Qualifiers** — Inject subsets of components with `Annotated[List[T], Qualifier(...)]`.
+* **Async Event Bus** — Built-in `EventBus` for decoupled, event-driven architecture.
+* **Conditional Registration** — `@conditional` (by profile, env var) and `@on_missing` (fallbacks).
+* **Lifecycle Hooks** — `@configure` (post-init) and `@cleanup` (on shutdown).
+* **Health Checks** — Built-in `@health` decorator and `container.health_check()`.
+* **Serializable Proxies** — Lazy (`@lazy`) and AOP proxies are `pickle`-safe.
+
+---
+
+## 📦 Installation
+
+```bash
+# Requires Python 3.10+
+pip install pico-ioc
+````
+
+-----
+
+## 🚀 Quick Start
+
+```python
+from pico_ioc import component, init, configuration
+from dataclasses import dataclass
+
+@configuration
+@dataclass
+class Config:
+    url: str = "sqlite:///demo.db"
+
+@component
+class Repo:
+    def __init__(self, cfg: Config):
+        self.url = cfg.url
+    def fetch(self): 
+        return f"fetching from {self.url}"
+
+@component
+class Service:
+    def __init__(self, repo: Repo):
+        self.repo = repo
+    def run(self): 
+        return self.repo.fetch()
+
+# Bootstrap the container by scanning modules
+# We use __name__ to scan the current module
+container = init(modules=[__name__])
+
+# Resolve the service and run
+svc = container.get(Service)
+print(svc.run())
+```
+
+**Output:**
+
+```
+fetching from sqlite:///demo.db
+```
+
+-----
+
+### Quick Overrides for Testing
+
+The `init` function accepts `overrides` to replace any component for testing.
+
+```python
+import my_app_module
+from pico_ioc import init
+
+# Define a fake repository
+class FakeRepo:
+    def fetch(self): 
+        return "fake-data"
+
+# Initialize the container, overriding the real Repo
+container = init(
+    modules=[my_app_module],
+    overrides={
+        Repo: FakeRepo()  # Override by type
+    }
+)
+
+# The service now receives FakeRepo instead of the real one
+svc = container.get(Service)
+assert svc.run() == "fake-data"
+```
+
+-----
+
+## 📖 Documentation
+
+  * **🚀 New to pico-ioc? Start with the User Guide.**
+
+      * [**guide.md**](.docs/guide.md) — Learn with practical examples: testing, configuration, AOP, async, and web framework integration.
+
+  * **🏗️ Want to understand the internals? See the Architecture.**
+
+      * [**architecture.md**](./docs/architecture.md) — A deep dive into the resolution algorithm, lifecycle, and internal design.
+
+-----
+
+## 🧪 Development
+
+```bash
+pip install tox
+tox
+```
+
+-----
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+-----
+
+## 📜 License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
+
+```
+```
+
+

pico_ioc-2.0.0/docs/DECISIONS.md

@@ -0,0 +1,156 @@
+# DECISIONS.md — pico-ioc
+
+This document records **technical and architectural decisions** for pico-ioc.
+Each entry includes a rationale and implications. If a decision is later changed, mark it **[REVOKED]** and link to the replacement.
+
+---
+
+## ✅ Current Decisions (Reflecting v2 Architecture)
+
+### 1) Minimum Python version: **3.10**
+**Decision**: Require Python **3.10+**.
+**Rationale**: `typing.Annotated` and improved `get_type_hints` are crucial for qualifiers, list injection, and clean internal implementation.
+**Implications**: Users must use Python 3.10 or newer. CI/CD targets 3.10+.
+
+---
+
+### 2) Keys: **Typed keys preferred**
+**Decision**: Primarily use class/type keys (e.g., `UserService`) for registration and resolution. String keys are supported but discouraged.
+**Rationale**: Enhances type safety, IDE support, and reduces potential collisions.
+**Implications**: Documentation emphasizes type-based injection. String keys remain for specific cases (e.g., configuration values, legacy integration).
+
+---
+
+### 3) Default Lifecycle: **Singleton per container**
+**Decision**: The default scope for components (`@component`) is `singleton`. One instance is created per container and cached.
+**Rationale**: Simple, fast, and matches common use cases for services and clients.
+**Implications**: Users must explicitly use `@scope("prototype")` or other scope decorators for different lifecycles.
+
+---
+
+### 4) Fail-Fast Bootstrap: **Eager Validation**
+**Decision**: Perform **eager validation** of component dependencies during `init()`. Check if a provider exists for every required dependency (excluding `@lazy` components by default).
+**Rationale**: Surface wiring errors (missing providers) immediately at startup, enhancing reliability over runtime failures.
+**Implications**: Increases startup time slightly. Potential `ProviderNotFoundError` for dependencies only used by `@lazy` components may be deferred until first access. *(See ADR-006)*
+
+---
+
+### 5) Qualifiers & Collection Injection: **First-class via `Annotated`**
+**Decision**: Support `Qualifier` tags via `@qualifier(...)` and inject filtered lists using `typing.Annotated[List[Type], Qualifier(...)]`.
+**Rationale**: Provides a standard, type-safe mechanism for managing multiple implementations of an interface without custom registries.
+**Implications**: Requires Python 3.9+ for `Annotated`. Preserves registration order in injected lists.
+
+---
+
+### 6) Overrides in `init(...)`
+**Decision**: Allow replacing components at bootstrap via `init(..., overrides={...})`.
+**Rationale**: Simplifies unit testing and mocking without needing complex setup or separate modules.
+**Implications**: Overrides are applied *before* any instances are created. Supports overriding with instances, callables (providers), or `(callable, lazy_bool)`.
+
+---
+
+### 7) Conditional Providers: **Profiles, Env Vars, Predicates**
+**Decision**: Support conditional registration using `@conditional(profiles=..., require_env=..., predicate=...)`.
+**Rationale**: Enables environment-specific configurations (prod vs. test vs. dev), feature flags, and optional integrations declaratively.
+**Implications**: Components might not be registered if conditions aren't met, potentially leading to `ProviderNotFoundError` if depended upon. Bootstrap error occurs if a required *eager* dependency is inactive. *(See ADR-006)*
+
+---
+
+### 8) Deterministic Provider Selection: **Prefer `@primary`**
+**Decision**: When multiple providers implement the same key (type), select the one marked `@primary`. If ambiguity remains, raise `InvalidBindingError`. `@on_missing` acts as a fallback if no primary or direct provider is found.
+**Rationale**: Provides explicit control over default implementations, making wiring predictable. Avoids reliance on implicit scan order.
+**Implications**: Developers must use `@primary` (or qualifiers/overrides) to resolve ambiguity between multiple implementations.
+
+---
+
+### 9) Concurrency & Safety: **Immutable Container, Context-Aware Scopes**
+**Decision**: The container's configuration (providers, metadata) is **immutable** after `init()`. Caches (`singleton`, `request`, etc.) are isolated and thread/task-safe using appropriate locking or `contextvars`.
+**Rationale**: Ensure safe usage in multi-threaded and asynchronous applications without external locking.
+**Implications**: Components themselves must be thread/task-safe if used concurrently across scopes. `contextvars` require proper context propagation in complex threading/async scenarios.
+
+---
+
+### 10) Configuration: **Dual System (`@configuration` and `@configured`)**
+**Decision**: Support two configuration injection mechanisms:
+    1. **`@configuration`**: For simple, flat key-value settings populated from ordered `ConfigSource`s (`EnvSource`, `FileSource`).
+    2. **`@configured`**: For complex, nested configuration trees populated from ordered `TreeSource`s (`YamlTreeSource`, `JsonTreeSource`), mapping directly to `dataclass` graphs.
+**Rationale**: `@configuration` handles simple cases easily. `@configured` provides a powerful, type-safe solution for modern, structured configuration practices, inspired by frameworks like Spring Boot.
+**Implications**: Developers choose the system appropriate for their needs. `@configured` is generally recommended for new, complex applications. *(See ADR-002)*
+
+---
+
+### 11) AOP: **Explicit Proxy via `@intercepted_by`**
+**Decision**: Implement AOP using **method interception** via a dynamic **`UnifiedComponentProxy`**. Interceptors are defined using the `MethodInterceptor` protocol and applied explicitly with `@intercepted_by(...)`. Rejected alternatives involving metaclass programming or bytecode manipulation.
+**Rationale**: Provides powerful AOP capabilities using standard Python features (decorators, proxies). Explicit application (`@intercepted_by`) is clearer and more controllable than global or rule-based interception. Avoids the complexity and potential fragility of metaprogramming/bytecode.
+**Implications**: Adds a proxy layer (minor performance overhead, potential debug complexity). Developers must explicitly decorate methods to apply aspects. *(See ADR-005)*
+
+---
+
+### 12) Async Support: **Native Integration**
+**Decision**: Integrate `asyncio` support deeply throughout the container. Provide `container.aget()`, support `async def` providers, `__ainit__`, async lifecycle hooks (`@configure`, `@cleanup`), async AOP, and an async Event Bus.
+**Rationale**: Essential for modern I/O-bound Python applications. Avoids blocking the event loop during component resolution or lifecycle management.
+**Implications**: Dual API (`get`/`aget`). Developers must use `aget` and `cleanup_all_async` in async contexts. *(See ADR-001)*
+
+---
+
+### 13) Context-Aware Scopes: **`contextvars`-Based**
+**Decision**: Implement dynamic scopes (`request`, `session`, custom) using `contextvars`. Provide `ScopeProtocol`, `ContextVarScope`, `ScopeManager`, `ScopedCaches` (with LRU), and `with container.scope(...)`.
+**Rationale**: `contextvars` provide a robust mechanism for managing context-local state in both threaded and async environments. Enables per-request or other contextual lifecycles.
+**Implications**: Requires explicit scope management (e.g., via middleware) using `container.scope()` or `activate/deactivate`. Potential complexity with context propagation in advanced scenarios. *(See ADR-003)*
+
+---
+
+### 14) Observability: **Built-in Features**
+**Decision**: Include features for monitoring and debugging: `container_id`, `container context` (`as_current`), `container.stats()`, `ContainerObserver` protocol, and `container.export_graph()`.
+**Rationale**: Essential for understanding and managing complex applications, especially multi-container setups. Makes the container less of a "black box".
+**Implications**: Slight overhead for context tracking. `ContainerObserver` and `export_graph` are optional features. *(See ADR-004)*
+
+---
+
+### 15) Event Bus: **Integrated Async Pub/Sub**
+**Decision**: Provide a built-in, asynchronous `EventBus` component with `@subscribe` decorator and `AutoSubscriberMixin`.
+**Rationale**: Facilitates decoupled, event-driven architectures directly within the container ecosystem. Provides a standard mechanism over ad-hoc solutions.
+**Implications**: Adds functionality beyond core DI. Requires registering the `pico_ioc.event_bus` module. Bus is in-process, not a distributed queue replacement. *(See ADR-007)*
+
+---
+
+## ❌ Won’t-Do Decisions (Confirmed for v2)
+
+### A) Alternative scopes (request/session) beyond `contextvars`
+**Decision**: Stick to `contextvars` for built-in dynamic scopes. Do not add framework-specific scope implementations (e.g., Flask `g`, Django `request`) directly into the core library.
+**Rationale**: Keep `pico-ioc` framework-agnostic. `contextvars` provide a universal mechanism. Framework integrations can bridge framework contexts to `pico-ioc` scopes if needed.
+**Implications**: Integration recipes (like for Flask/FastAPI) show how to manage `contextvars`-based scopes using middleware or request hooks.
+
+### B) Hot reload / dynamic re-scan
+**Decision**: The container configuration remains **immutable** after `init()`. No built-in support for watching files and automatically reloading the container.
+**Rationale**: Conflicts with fail-fast validation and immutability principles. Adds significant complexity and potential for inconsistent states. Hot-reload is better handled by development server tools (like `uvicorn --reload` or the `watchdog` pattern shown in the cookbook).
+**Implications**: Developers use external tools or patterns (like the cookbook example) for development-time hot-reloading.
+
+---
+
+## 🗃️ Deprecated / Revoked
+
+* **[REVOKED] Decision #11 (Old)**: Infrastructure-based Interceptor API via `@infrastructure`.
+    * **Reason:** Replaced by the simpler, more explicit `@intercepted_by` AOP mechanism using `UnifiedComponentProxy` (ADR-005). The `@infrastructure` role might be repurposed or removed in future versions.
+
+---
+
+## 📜 Changelog of Decisions (v2 Focus)
+
+* **v2.0**: Minimum Python **3.10** adopted.
+* **v2.0**: **Native Async Support** added (`aget`, `__ainit__`, async hooks/AOP/EventBus - ADR-001).
+* **v2.0**: **Tree-Based Configuration Binding** added (`@configured`, `TreeSource`, `ConfigResolver`, `ObjectGraphBuilder` - ADR-002).
+* **v2.0**: **Context-Aware Scopes** implemented (`@scope("request")`, `contextvars`, `container.scope()` - ADR-003).
+* **v2.0**: **Observability Features** added (`container_id`, `as_current`, `stats`, `ContainerObserver`, `export_graph` - ADR-004).
+* **v2.0**: **AOP Implementation** finalized using `@intercepted_by` and `UnifiedComponentProxy` (ADR-005). Explicit decision against metaprogramming. Old `@infrastructure`-based interceptor plan revoked.
+* **v2.0**: **Eager Startup Validation** confirmed as core principle (ADR-006).
+* **v2.0**: **Built-in Async Event Bus** added (ADR-007).
+* **v2.0**: **`@primary`** confirmed as the primary mechanism for resolving ambiguity (Decision #8 refined).
+* **v2.0**: **Configuration Injection** clarified as a dual system (`@configuration` + `@configured`) (Decision #10 updated).
+
+---
+
+**Summary**: `pico-ioc` v2 prioritizes **robustness, async-native operation, powerful configuration, observability, and explicit AOP** using standard Python features. It remains deterministic and aims to fail fast at startup.
+```
+
+How does this look? It incorporates the key decisions from the ADRs and clarifies the v2 architecture.

pico_ioc-2.0.0/docs/README.md

@@ -0,0 +1,96 @@
+# Welcome to pico-ioc
+
+`pico-ioc` is a powerful, async-native, and observability-first Inversion of Control (IoC) container for Python. It's designed to bring the power of enterprise-grade dependency injection, configuration binding, and AOP (Aspect-Oriented Programming) from frameworks like Spring into the modern Python ecosystem.
+
+This documentation site guides you from your first component to building complex, observable, and testable applications.
+
+## Key Features
+
+* 🚀 **Async-Native:** Full support for `async`/`await` in component resolution (`aget`), lifecycle methods (`__ainit__`, `@cleanup`), AOP interceptors, and the Event Bus.
+* 🌳 **Advanced Tree-Binding:** Use `@configured` to map complex YAML/JSON configuration trees directly to `dataclass` graphs, including support for `Union` types and custom discriminators.
+* 🔬 **Observability-First:** Built-in container contexts (`as_current`), stats (`.stats()`), and observer protocols (`ContainerObserver`) to monitor, trace, and debug your application's components.
+* ✨ **Powerful AOP:** Intercept method calls for cross-cutting concerns (like logging, tracing, or caching) using `@intercepted_by` without modifying your business logic.
+* ✅ **Fail-Fast Validation:** The container validates all component dependencies at startup (`init()`), preventing `ProviderNotFoundError` exceptions at runtime.
+* 🧩 **Rich Lifecycle:** Full control over component lifecycles with `@scope`, `@lazy` instantiation, `@configure` setup methods, and `@cleanup` teardown hooks.
+
+## Documentation Structure
+
+### 1. Getting Started
+
+Start here for a 5-minute tutorial to get `pico-ioc` running.
+
+* [Overview](./getting-started/README.md)
+* [Installation](./getting-started/installation.md)
+* [5-Minute Quick Start](./getting-started/quick-start.md)
+
+### 2. User Guide
+
+The main guide covering the 80% of features you'll use daily.
+
+* [Overview](./user-guide/README.md)
+* [Core Concepts (`@component`, `@factory`)](./user-guide/core-concepts.md)
+* [Basic Configuration (`@configuration`)](./user-guide/configuration-basic.md)
+* [Configuration Tree Binding (`@configured`)](./user-guide/configuration-binding.md)
+* [Scopes, Lifecycle & `@lazy`](./user-guide/scopes-lifecycle.md)
+* [Qualifiers & List Injection](./user-guide/qualifiers-lists.md)
+* [Testing Applications](./user-guide/testing.md)
+
+### 3. Advanced Features
+
+Powerful features for complex application architectures.
+
+* [Overview](./advanced-features/README.md)
+* [Async Resolution (`aget`, `__ainit__`)](./advanced-features/async-resolution.md)
+* [AOP & Interceptors](./advanced-features/aop-interceptors.md)
+* [The Event Bus](./advanced-features/event-bus.md)
+* [Conditional Binding (`@conditional`, `@primary`)](./advanced-features/conditional-binding.md)
+* [Health Checks (`@health`)](./advanced-features/health-checks.md)
+
+### 4. Observability
+
+Monitor, trace, and debug your application's components.
+
+* [Overview](./observability/README.md)
+* [Container Context (`as_current`)](./observability/container-context.md)
+* [Observers & Metrics (`stats`)](./observability/observers-metrics.md)
+* [Exporting the Dependency Graph](./observability/exporting-graph.md)
+
+### 5. Integrations
+
+Recipes for using `pico-ioc` with popular frameworks.
+
+* [Overview](./integrations/README.md)
+* [FastAPI](./integrations/web-fastapi.md)
+* [Flask](./integrations/web-flask.md)
+* [Django](./integrations/web-django.md)
+* [AI & LangChain](./integrations/ai-langchain.md)
+
+### 6. Cookbook (Patterns)
+
+Complete, copy-paste examples of common architectural patterns.
+
+* [Overview](./cookbook/README.md)
+* [Pattern: Multi-Tenant Applications](./cookbook/pattern-multi-tenant.md)
+* [Pattern: Hot Reload (Dev Server)](./cookbook/pattern-hot-reload.md)
+* [Pattern: CLI Applications](./cookbook/pattern-cli-app.md)
+
+### 7. Architecture
+
+The "Why" and "How" behind `pico-ioc`'s design.
+
+* [Overview](./architecture/README.md)
+* [Design Principles](./architecture/design-principles.md)
+* [Comparison to Other Libraries](./architecture/comparison.md)
+* [Internals Deep-Dive](./architecture/internals.md)
+
+### 8. API Reference
+
+A "cheatsheet" for all public APIs.
+
+* [Overview](./api-reference/README.md)
+* [Glossary](./api-reference/glossary.md)
+* [Decorators Reference](./api-reference/decorators.md)
+* [`PicoContainer` API](./api-reference/container.md)
+* [Protocols (`MethodInterceptor`, etc.)](./api-reference/protocols.md)
+```
+