pico-ioc 2.0.4__tar.gz → 2.1.0__tar.gz

{pico_ioc-2.0.4 → pico_ioc-2.1.0}/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.html).
 
+
+---
+
+## [2.1.0] - 2025-10-28
+
+### Added ✨
+
+* **Unified Configuration Builder (`configuration(...)`)**: Introduced a new top-level function `configuration(...)` that accepts various sources (`EnvSource`, `DictSource`, `JsonTreeSource`, `YamlTreeSource`, `FlatDictSource`, etc.) and `overrides` to produce an immutable `ContextConfig` object. This centralizes configuration definition and precedence rules (ADR-010).
+* **`ContextConfig` Object**: A new object encapsulating the fully processed configuration state, passed to `init(config=...)`.
+* **Enhanced `@configured` Decorator**:
+    * Added `mapping: Literal["auto", "flat", "tree"]` parameter to explicitly control binding strategy.
+    * Implemented `"auto"` detection: uses `"tree"` if any field is complex (dataclass, list, dict, Union), otherwise uses `"flat"`.
+    * Supports unified normalization rules for keys (e.g., `ENV_VAR_NAME` <-> `field_name`, `ENV_VAR__NESTED` <-> `parent.nested`).
+    * Integrates seamlessly with both flat and tree sources managed by `ContextConfig`.
+
+### Changed ⚠️
+
+* **`init()` Signature**: The `config` and `tree_config` parameters have been removed. Configuration is now passed solely through the new `config: Optional[ContextConfig]` parameter (ADR-010).
+* **Configuration Precedence**: Configuration loading and precedence are now strictly defined by the order of sources passed to the `configuration(...)` builder, followed by its `overrides` parameter, and finally `Annotated[..., Value(...)]` (ADR-010).
+
+### Removed ❌
+
+* **`@configuration` Decorator**: This decorator, previously used for flat key-value binding, has been completely removed in favor of the unified `@configured` decorator (ADR-010).
+* Separate `config` (flat) and `tree_config` arguments in `init()`.
+
+### Documentation 📚
+
+* Updated all documentation (User Guide, API Reference, Examples, ADRs) to reflect the unified configuration system based on `@configured`, `configuration(...)`, and `ContextConfig`.
+* Added `docs/specs/spec-configuration.md` detailing the unified configuration rules.
+* Added migration notes related to removing `@configuration`.
+
+### Breaking Changes ⚠️
+
+* This release introduces **significant breaking changes** related to configuration management, requiring migration from the old `@configuration` decorator and `init()` arguments to the new `@configured` modes and `configuration(...)` builder (ADR-010).
+
 ---
 
 ## [2.0.3] - 2025-10-26

{pico_ioc-2.0.4 → pico_ioc-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.0.4
+Version: 2.1.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -68,13 +68,13 @@ It brings *Inversion of Control* and *dependency injection* to Python in a deter
 
 ## ⚖️ Core Principles
 
--   **Single Purpose** – Do one thing: dependency management.
--   **Declarative** – Use simple decorators (`@component`, `@factory`, `@configuration`) instead of config files or YAML magic.
--   **Deterministic** – No hidden scanning or side-effects; everything flows from an explicit `init()`.
--   **Async-Native** – Fully supports async providers, async lifecycle hooks, and async interceptors.
--   **Fail-Fast** – Detects missing bindings and circular dependencies at bootstrap.
--   **Testable by Design** – Use `overrides` and `profiles` to swap components instantly.
--   **Zero Core Dependencies** – Built entirely on the Python standard library. Optional features may require external packages (see Installation).
+- **Single Purpose** – Do one thing: dependency management.
+- **Declarative** – Use simple decorators (`@component`, `@factory`, `@provides`, `@configured`) instead of complex config files.
+- **Deterministic** – No hidden scanning or side-effects; everything flows from an explicit `init()`.
+- **Async-Native** – Fully supports async providers, async lifecycle hooks (`__ainit__`), and async interceptors.
+- **Fail-Fast** – Detects missing bindings and circular dependencies at bootstrap (`init()`).
+- **Testable by Design** – Use `overrides` and `profiles` to swap components instantly.
+- **Zero Core Dependencies** – Built entirely on the Python standard library. Optional features may require external packages (see Installation).
 
 ---
 
@@ -83,25 +83,24 @@ It brings *Inversion of Control* and *dependency injection* to Python in a deter
 As Python systems evolve, wiring dependencies by hand becomes fragile and unmaintainable.
 **Pico-IoC** eliminates that friction by letting you declare how components relate — not how they’re created.
 
-| Feature        | Manual Wiring              | With Pico-IoC                   |
-| :------------- | :------------------------- | :------------------------------ |
-| Object creation| `svc = Service(Repo(Config()))` | `svc = container.get(Service)`  |
-| Replacing deps | Monkey-patch               | `overrides={Repo: FakeRepo()}`  |
-| Coupling       | Tight                      | Loose                           |
-| Testing        | Painful                    | Instant                         |
-| Async support  | Manual                     | Built-in                        |
+| Feature         | Manual Wiring              | With Pico-IoC                     |
+| :-------------- | :------------------------- | :-------------------------------- |
+| Object creation | `svc = Service(Repo(Config()))` | `svc = container.get(Service)`    |
+| Replacing deps  | Monkey-patch               | `overrides={Repo: FakeRepo()}`    |
+| Coupling        | Tight                      | Loose                             |
+| Testing         | Painful                    | Instant                           |
+| Async support   | Manual                     | Built-in (`aget`, `__ainit__`, ...) |
 
 ---
 
-## 🧩 Highlights (v2.0.0)
+## 🧩 Highlights (v2.0+)
 
--   **Full redesign:** unified architecture with simpler, more powerful APIs.
--   **Async-aware AOP system** — method interceptors via `@intercepted_by`.
--   **Typed configuration** — dataclasses with JSON/YAML/env sources.
--   **Scoped resolution** — singleton, prototype, request, session, transaction.
--   **UnifiedComponentProxy** — transparent lazy/AOP proxy supporting serialization.
--   **Tree-based configuration runtime** with reusable adapters and discriminators.
--   **Observable container context** with stats, health checks, and async cleanup.
+- **Unified Configuration:** Use `@configured` to bind both **flat** (ENV-like) and **tree** (YAML/JSON) sources via the `configuration(...)` builder (ADR-0010).
+- **Async-aware AOP system:** Method interceptors via `@intercepted_by`.
+- **Scoped resolution:** singleton, prototype, request, session, transaction, and custom scopes.
+- **`UnifiedComponentProxy`:** Transparent `lazy=True` and AOP proxy supporting serialization.
+- **Tree-based configuration runtime:** Advanced mapping with reusable adapters and discriminators (`Annotated[Union[...], Discriminator(...)]`).
+- **Observable container context:** Built-in stats, health checks (`@health`), observer hooks (`ContainerObserver`), dependency graph export (`export_graph`), and async cleanup.
 
 ---
 
@@ -109,7 +108,7 @@ As Python systems evolve, wiring dependencies by hand becomes fragile and unmain
 
 ```bash
 pip install pico-ioc
-```
+````
 
 For optional features, you can install extras:
 
@@ -121,50 +120,68 @@ For optional features, you can install extras:
 
     (Requires `PyYAML`)
 
-  * **Dependency Graph Export:**
+  * **Dependency Graph Export (Rendering):**
 
     ```bash
-    pip install pico-ioc[graphviz]
+    # You still need Graphviz command-line tools installed separately
+    # This extra is currently not required by the code,
+    # as export_graph generates the .dot file content directly.
+    # pip install pico-ioc[graphviz] # Consider removing if not used by code
     ```
 
-    (Requires the `graphviz` Python package and the Graphviz command-line tools)
-
 -----
 
-## ⚙️ Quick Example
+## ⚙️ Quick Example (Unified Configuration)
 
 ```python
+import os
 from dataclasses import dataclass
-from pico_ioc import component, configuration, init
+from pico_ioc import component, configured, configuration, init, EnvSource
 
-@configuration
+# 1. Define configuration with @configured
+@configured(prefix="APP_", mapping="auto") # Auto-detects flat mapping
 @dataclass
 class Config:
     db_url: str = "sqlite:///demo.db"
 
+# 2. Define components
 @component
 class Repo:
-    def __init__(self, cfg: Config):
+    def __init__(self, cfg: Config): # Inject config
         self.cfg = cfg
     def fetch(self):
         return f"fetching from {self.cfg.db_url}"
 
 @component
 class Service:
-    def __init__(self, repo: Repo):
+    def __init__(self, repo: Repo): # Inject Repo
         self.repo = repo
     def run(self):
         return self.repo.fetch()
 
-container = init(modules=[__name__])
+# --- Example Setup ---
+os.environ['APP_DB_URL'] = 'postgresql://user:pass@host/db'
+
+# 3. Build configuration context
+config_ctx = configuration(
+    EnvSource(prefix="") # Read APP_DB_URL from environment
+)
+
+# 4. Initialize container
+container = init(modules=[__name__], config=config_ctx) # Pass context via 'config'
+
+# 5. Get and use the service
 svc = container.get(Service)
 print(svc.run())
+
+# --- Cleanup ---
+del os.environ['APP_DB_URL']
 ```
 
 **Output:**
 
 ```
-fetching from sqlite:///demo.db
+fetching from postgresql://user:pass@host/db
 ```
 
 -----
@@ -175,7 +192,16 @@ fetching from sqlite:///demo.db
 class FakeRepo:
     def fetch(self): return "fake-data"
 
-container = init(modules=[__name__], overrides={Repo: FakeRepo()})
+# Build configuration context (might be empty or specific for test)
+test_config_ctx = configuration()
+
+# Use overrides during init
+container = init(
+    modules=[__name__],
+    config=test_config_ctx,
+    overrides={Repo: FakeRepo()} # Replace Repo with FakeRepo
+)
+
 svc = container.get(Service)
 assert svc.run() == "fake-data"
 ```
@@ -185,23 +211,46 @@ assert svc.run() == "fake-data"
 ## 🩺 Lifecycle & AOP
 
 ```python
-from pico_ioc import intercepted_by, MethodInterceptor, MethodCtx
+import time # For example
+from pico_ioc import component, init, intercepted_by, MethodInterceptor, MethodCtx
 
+# Define an interceptor component
+@component
 class LogInterceptor(MethodInterceptor):
     def invoke(self, ctx: MethodCtx, call_next):
-        print(f"→ calling {ctx.name}")
-        res = call_next(ctx)
-        print(f"← {ctx.name} done")
-        return res
+        print(f"→ calling {ctx.cls.__name__}.{ctx.name}")
+        start = time.perf_counter()
+        try:
+            res = call_next(ctx)
+            duration = (time.perf_counter() - start) * 1000
+            print(f"← {ctx.cls.__name__}.{ctx.name} done ({duration:.2f}ms)")
+            return res
+        except Exception as e:
+            duration = (time.perf_counter() - start) * 1000
+            print(f"← {ctx.cls.__name__}.{ctx.name} failed ({duration:.2f}ms): {e}")
+            raise
 
 @component
 class Demo:
-    @intercepted_by(LogInterceptor)
+    @intercepted_by(LogInterceptor) # Apply the interceptor
     def work(self):
+        print("   Working...")
+        time.sleep(0.01)
         return "ok"
 
+# Initialize container (must scan module containing interceptor too)
 c = init(modules=[__name__])
-c.get(Demo).work()
+result = c.get(Demo).work()
+print(f"Result: {result}")
+```
+
+**Output:**
+
+```
+→ calling Demo.work
+   Working...
+← Demo.work done (10.xxms)
+Result: ok
 ```
 
 -----
@@ -233,7 +282,7 @@ tox
 
 ## 🧾 Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) — *Full redesign for v2.0.0.*
+See [CHANGELOG.md](./CHANGELOG.md) — *Significant redesigns and features in v2.0+.*
 
 -----
 

pico_ioc-2.1.0/README.md

@@ -0,0 +1,242 @@
+# 📦 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 **lightweight, async-ready, decorator-driven IoC container** built for clarity, testability, and performance.
+It brings *Inversion of Control* and *dependency injection* to Python in a deterministic, modern, and framework-agnostic way.
+
+> 🐍 Requires **Python 3.10+**
+
+---
+
+## ⚖️ Core Principles
+
+- **Single Purpose** – Do one thing: dependency management.
+- **Declarative** – Use simple decorators (`@component`, `@factory`, `@provides`, `@configured`) instead of complex config files.
+- **Deterministic** – No hidden scanning or side-effects; everything flows from an explicit `init()`.
+- **Async-Native** – Fully supports async providers, async lifecycle hooks (`__ainit__`), and async interceptors.
+- **Fail-Fast** – Detects missing bindings and circular dependencies at bootstrap (`init()`).
+- **Testable by Design** – Use `overrides` and `profiles` to swap components instantly.
+- **Zero Core Dependencies** – Built entirely on the Python standard library. Optional features may require external packages (see Installation).
+
+---
+
+## 🚀 Why Pico-IoC?
+
+As Python systems evolve, wiring dependencies by hand becomes fragile and unmaintainable.
+**Pico-IoC** eliminates that friction by letting you declare how components relate — not how they’re created.
+
+| Feature         | Manual Wiring              | With Pico-IoC                     |
+| :-------------- | :------------------------- | :-------------------------------- |
+| Object creation | `svc = Service(Repo(Config()))` | `svc = container.get(Service)`    |
+| Replacing deps  | Monkey-patch               | `overrides={Repo: FakeRepo()}`    |
+| Coupling        | Tight                      | Loose                             |
+| Testing         | Painful                    | Instant                           |
+| Async support   | Manual                     | Built-in (`aget`, `__ainit__`, ...) |
+
+---
+
+## 🧩 Highlights (v2.0+)
+
+- **Unified Configuration:** Use `@configured` to bind both **flat** (ENV-like) and **tree** (YAML/JSON) sources via the `configuration(...)` builder (ADR-0010).
+- **Async-aware AOP system:** Method interceptors via `@intercepted_by`.
+- **Scoped resolution:** singleton, prototype, request, session, transaction, and custom scopes.
+- **`UnifiedComponentProxy`:** Transparent `lazy=True` and AOP proxy supporting serialization.
+- **Tree-based configuration runtime:** Advanced mapping with reusable adapters and discriminators (`Annotated[Union[...], Discriminator(...)]`).
+- **Observable container context:** Built-in stats, health checks (`@health`), observer hooks (`ContainerObserver`), dependency graph export (`export_graph`), and async cleanup.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pico-ioc
+````
+
+For optional features, you can install extras:
+
+  * **YAML Configuration:**
+
+    ```bash
+    pip install pico-ioc[yaml]
+    ```
+
+    (Requires `PyYAML`)
+
+  * **Dependency Graph Export (Rendering):**
+
+    ```bash
+    # You still need Graphviz command-line tools installed separately
+    # This extra is currently not required by the code,
+    # as export_graph generates the .dot file content directly.
+    # pip install pico-ioc[graphviz] # Consider removing if not used by code
+    ```
+
+-----
+
+## ⚙️ Quick Example (Unified Configuration)
+
+```python
+import os
+from dataclasses import dataclass
+from pico_ioc import component, configured, configuration, init, EnvSource
+
+# 1. Define configuration with @configured
+@configured(prefix="APP_", mapping="auto") # Auto-detects flat mapping
+@dataclass
+class Config:
+    db_url: str = "sqlite:///demo.db"
+
+# 2. Define components
+@component
+class Repo:
+    def __init__(self, cfg: Config): # Inject config
+        self.cfg = cfg
+    def fetch(self):
+        return f"fetching from {self.cfg.db_url}"
+
+@component
+class Service:
+    def __init__(self, repo: Repo): # Inject Repo
+        self.repo = repo
+    def run(self):
+        return self.repo.fetch()
+
+# --- Example Setup ---
+os.environ['APP_DB_URL'] = 'postgresql://user:pass@host/db'
+
+# 3. Build configuration context
+config_ctx = configuration(
+    EnvSource(prefix="") # Read APP_DB_URL from environment
+)
+
+# 4. Initialize container
+container = init(modules=[__name__], config=config_ctx) # Pass context via 'config'
+
+# 5. Get and use the service
+svc = container.get(Service)
+print(svc.run())
+
+# --- Cleanup ---
+del os.environ['APP_DB_URL']
+```
+
+**Output:**
+
+```
+fetching from postgresql://user:pass@host/db
+```
+
+-----
+
+## 🧪 Testing with Overrides
+
+```python
+class FakeRepo:
+    def fetch(self): return "fake-data"
+
+# Build configuration context (might be empty or specific for test)
+test_config_ctx = configuration()
+
+# Use overrides during init
+container = init(
+    modules=[__name__],
+    config=test_config_ctx,
+    overrides={Repo: FakeRepo()} # Replace Repo with FakeRepo
+)
+
+svc = container.get(Service)
+assert svc.run() == "fake-data"
+```
+
+-----
+
+## 🩺 Lifecycle & AOP
+
+```python
+import time # For example
+from pico_ioc import component, init, intercepted_by, MethodInterceptor, MethodCtx
+
+# Define an interceptor component
+@component
+class LogInterceptor(MethodInterceptor):
+    def invoke(self, ctx: MethodCtx, call_next):
+        print(f"→ calling {ctx.cls.__name__}.{ctx.name}")
+        start = time.perf_counter()
+        try:
+            res = call_next(ctx)
+            duration = (time.perf_counter() - start) * 1000
+            print(f"← {ctx.cls.__name__}.{ctx.name} done ({duration:.2f}ms)")
+            return res
+        except Exception as e:
+            duration = (time.perf_counter() - start) * 1000
+            print(f"← {ctx.cls.__name__}.{ctx.name} failed ({duration:.2f}ms): {e}")
+            raise
+
+@component
+class Demo:
+    @intercepted_by(LogInterceptor) # Apply the interceptor
+    def work(self):
+        print("   Working...")
+        time.sleep(0.01)
+        return "ok"
+
+# Initialize container (must scan module containing interceptor too)
+c = init(modules=[__name__])
+result = c.get(Demo).work()
+print(f"Result: {result}")
+```
+
+**Output:**
+
+```
+→ calling Demo.work
+   Working...
+← Demo.work done (10.xxms)
+Result: ok
+```
+
+-----
+
+## 📖 Documentation
+
+The full documentation is available within the `docs/` directory of the project repository. Start with `docs/README.md` for navigation.
+
+  * **Getting Started:** `docs/getting-started.md`
+  * **User Guide:** `docs/user-guide/README.md`
+  * **Advanced Features:** `docs/advanced-features/README.md`
+  * **Observability:** `docs/observability/README.md`
+  * **Integrations:** `docs/integrations/README.md`
+  * **Cookbook (Patterns):** `docs/cookbook/README.md`
+  * **Architecture:** `docs/architecture/README.md`
+  * **API Reference:** `docs/api-reference/README.md`
+  * **ADR Index:** `docs/adr/README.md`
+
+-----
+
+## 🧩 Development
+
+```bash
+pip install tox
+tox
+```
+
+-----
+
+## 🧾 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) — *Significant redesigns and features in v2.0+.*
+
+-----
+
+## 📜 License
+
+MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

{pico_ioc-2.0.4 → pico_ioc-2.1.0}/docs/README.md

@@ -7,7 +7,7 @@ This documentation site guides you from your first component to building complex
 ## 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.
+* 🌳 **Advanced Unified Configuration:** Use `@configured` to map complex YAML/JSON configuration trees *or* flat key-value sources (like ENV) directly to `dataclass` graphs via the `configuration(...)` builder, with clear precedence rules and normalization. # <-- Updated this point slightly for ADR-0010
 * 🔬 **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.
@@ -53,24 +53,25 @@ from pico_ioc import component, init
 
 # 1. Define your components
 class Greeter:
-    def say_hello(self) -> str: ...
+    def say_hello(self) -> str: ...
 
 @component
 class EnglishGreeter(Greeter):
-    def say_hello(self) -> str:
-        return "Hello!"
+    def say_hello(self) -> str:
+        return "Hello!"
 
 @component
 class App:
-    # 2. Declare dependencies in the constructor
-    def __init__(self, greeter: Greeter):
-        self.greeter = greeter
-    
-    def run(self):
-        print(self.greeter.say_hello())
+    # 2. Declare dependencies in the constructor
+    def __init__(self, greeter: Greeter):
+        self.greeter = greeter
+    
+    def run(self):
+        print(self.greeter.say_hello())
 
 # 3. Initialize the container
 # The 'modules' list tells pico_ioc where to scan for @component
+# This example doesn't need explicit configuration sources.
 container = init(modules=[__name__])
 
 # 4. Get the root component and run
@@ -80,10 +81,4 @@ app.run()
 # Output: Hello!
 ```
 
------
-
-##  Navigation
-
-| [⬅️ Anterior: Inicio](./README.md) | [🏠 Índice Principal](./README.md) | [Siguiente ➡️: Guía de Usuario](./user-guide/README.md) |
-| :--- | :--- | :--- |
 

{pico_ioc-2.0.4 → pico_ioc-2.1.0}/docs/adr/README.md

@@ -1,15 +1,18 @@
+Okay, here's the corrected index list for the Architecture Decision Records (ADRs):
+
 # Architecture Decision Records (ADRs)
 
 This index lists all significant architecture decisions for the `pico-ioc` project. Keep it sorted by ADR number.
 
 ---
 
-* [ADR-001: Native Asyncio Support](./adr-0001-async-native.md) — Accepted  
-* [ADR-002: Tree-Based Configuration](./adr-0002-tree-based-configuration.md) — Accepted  
-* [ADR-003: Context-Aware Scopes](./adr-0003-context-aware-scopes.md) — Accepted  
-* [ADR-004: Observability Features](./adr-0004-observability.md) — Accepted  
-* [ADR-005: Aspect-Oriented Programming (AOP)](./adr-0005-aop.md) — Accepted  
-* [ADR-006: Eager Validation](./adr-0006-eager-validation.md) — Accepted  
-* [ADR-007: Built-in Asynchronous Event Bus](./adr-0007-event_bus.md) — Accepted  
+* [ADR-001: Native Asyncio Support](./adr-0001-async-native.md) — Accepted
+* [ADR-002: Tree-Based Configuration](./adr-0002-tree-based-configuration.md) — Accepted (Partially Superseded by ADR-010)
+* [ADR-003: Context-Aware Scopes](./adr-0003-context-aware-scopes.md) — Accepted
+* [ADR-004: Observability Features](./adr-0004-observability.md) — Accepted
+* [ADR-005: Aspect-Oriented Programming (AOP)](./adr-0005-aop.md) — Accepted
+* [ADR-006: Eager Validation](./adr-0006-eager-validation.md) — Accepted
+* [ADR-007: Built-in Asynchronous Event Bus](./adr-0007-event_bus.md) — Accepted
 * [ADR-008: Explicit Handling of Circular Dependencies](./adr-0008-circular-dependencies.md) — Accepted
 * [ADR-009: Flexible @provides for Static and Module-level Functions](./adr-0009-flexible-provides.md) — Accepted
+* [ADR-010: Unified Configuration via `@configured` and `ContextConfig`](./adr-0010-unified-configuration.md) — Accepted

pico_ioc-2.1.0/docs/adr/adr-0002-tree-based-configuration.md

@@ -0,0 +1,33 @@
+# ADR-002: Tree-Based Configuration Binding
+
+**Status:** Accepted (Partially Superseded by [ADR-0010](./adr-0010-unified-configuration.md))
+
+> **Note:** While the core concepts of **tree-binding logic** (`ConfigResolver`, `ObjectGraphBuilder`) and using `@configured` for nested structures remain valid, **ADR-0010 unified the configuration system**. The mechanism described here using a separate `init(tree_config=...)` argument is **no longer current**. Configuration sources (including tree sources like `YamlTreeSource`) are now passed to the `configuration(...)` builder, and the resulting `ContextConfig` object is passed to `init(config=...)`. The `@configured` decorator now handles both flat and tree mapping via its `mapping` parameter.
+
+## Context
+
+Basic configuration (`@configuration` with `ConfigSource` - *now removed*) was suitable for flat key-value pairs but became cumbersome for complex, nested application settings common in modern microservices (e.g., configuring databases, caches, feature flags, external clients with nested properties). Manually parsing nested structures or using complex prefixes was error-prone and lacked type safety beyond simple primitives. We needed a way to map structured configuration files (like YAML or JSON) directly to Python object graphs (like `dataclasses`).
+
+## Decision
+
+We introduced a **dedicated tree-binding system**:
+
+1.  **`TreeSource` Protocol:** Defined sources that provide configuration as a nested `Mapping` (e.g., `YamlTreeSource`, `JsonTreeSource`). These are now passed to the **`configuration(...)` builder** *(updated per ADR-0010)*.
+2.  **`ConfigResolver`:** An internal component that loads, merges (sources are layered according to `configuration(...)` order), and interpolates (`${ENV:VAR}`, `${ref:path}`) all `TreeSource`s into a single, final configuration tree.
+3.  **`ObjectGraphBuilder`:** An internal component that recursively maps a sub-tree (selected by a `prefix`) from the `ConfigResolver` onto a target Python type (usually a `dataclass`). It handles type coercion, nested objects, lists, dictionaries, `Union`s (with `Discriminator`), and `Enum`s.
+4.  **`@configured(prefix="key", mapping="tree"|"auto")` Decorator:** *(Updated per ADR-0010)* A registration mechanism that tells `pico-ioc` to create a provider for the target type by using the `ObjectGraphBuilder` to map the configuration sub-tree found at `prefix`, when the `mapping` is determined to be `"tree"` (either explicitly or via `"auto"` detection).
+
+## Consequences
+
+**Positive:** 👍
+* Enables highly structured, type-safe configuration.
+* Configuration structure directly mirrors `dataclass` definitions, improving clarity.
+* Supports common formats like YAML and JSON naturally.
+* Interpolation allows for dynamic values and avoids repetition.
+* Decouples components from the *source* of configuration (env, file, etc.).
+* Polymorphic configuration (`Union` + `Discriminator`) allows for flexible setup (e.g., selecting different cache backends via config).
+
+**Negative:** 👎
+* *(Original negative points about having two systems are mostly resolved by ADR-0010)*
+* Requires understanding the mapping rules (prefix, type coercion, discriminators, `mapping` parameter).
+* Adds optional dependencies for formats like YAML (`pip install pico-ioc[yaml]`).