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

{pico_ioc-1.5.0 → pico_ioc-2.0.1}/.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.1/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+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.0.0] - 2025-10-23
+
+This version marks a significant redesign and the first major public release, establishing the core architecture and feature set based on the principles outlined in the Architecture Decision Records (ADRs).
+
+### 🚀 Highlights
+
+* **Async-Native Core:** Introduced first-class `async`/`await` support across component resolution (`container.aget`), initialization (`__ainit__`), lifecycle hooks (`@configure`, `@cleanup`), AOP interceptors, and the event bus (ADR-001).
+* **Tree-Based Configuration:** Added `@configured` decorator and `TreeSource` protocol for binding complex, nested configuration (YAML/JSON) to dataclass graphs, including interpolation and type coercion (ADR-002).
+* **Context-Aware Scopes:** Implemented `contextvars`-based scopes (e.g., `"request"`, `"session"`) for managing component lifecycles tied to specific contexts (ADR-003).
+* **Observability Features:** Integrated container context (`container_id`, `as_current`), basic stats (`container.stats()`), observer protocol (`ContainerObserver`), and dependency graph export (`container.export_graph()`) (ADR-004).
+* **Aspect-Oriented Programming (AOP):** Implemented method interception via `MethodInterceptor` protocol and `@intercepted_by` decorator, using a dynamic proxy (`UnifiedComponentProxy`) (ADR-005).
+* **Eager Startup Validation:** Added fail-fast validation during `init()` to detect missing dependencies and configuration errors before runtime (ADR-006).
+* **Built-in Event Bus:** Included an asynchronous, in-process event bus (`EventBus`, `@subscribe`, `AutoSubscriberMixin`) for decoupled communication (ADR-007).
+* **Explicit Circular Dependency Handling:** Implemented detection and fail-fast for circular dependencies, requiring explicit resolution patterns (ADR-008).
+* **Unified Decorator API:** Consolidated component metadata into parameterized decorators (`@component`, `@factory`, `@provides`), removing older stacked decorators (ADR-009).
+
+### ✨ Added
+
+* Core registration decorators: `@component`, `@factory`, `@provides`.
+* Configuration decorators: `@configuration` (flat key-value) and `@configured` (tree-based).
+* Lifecycle decorators: `@configure`, `@cleanup`.
+* AOP decorator: `@intercepted_by`.
+* Event bus decorator: `@subscribe`.
+* Health check decorator: `@health`.
+* Async resolution: `container.aget()` and `__ainit__` convention.
+* Async cleanup: `container.cleanup_all_async()`.
+* Qualifier support (`Qualifier` class) for list injection (`Annotated[List[Type], Qualifier(...)]`).
+* Support for `lazy=True` parameter for deferred component instantiation.
+* Conditional binding parameters (`conditional_profiles`, `conditional_require_env`, `conditional_predicate`).
+* Fallback binding parameters (`on_missing_selector`, `on_missing_priority`).
+* Primary selection parameter (`primary=True`).
+* Testing support via `init(overrides={...})` and `init(profiles=(...))`.
+* Container context management (`as_current`, `get_current`, `shutdown`, `all_containers`).
+* Scope management API (`activate_scope`, `deactivate_scope`, `scope` context manager).
+* Configuration sources: `EnvSource`, `FileSource` (flat); `JsonTreeSource`, `YamlTreeSource`, `DictSource` (tree).
+* Protocols for extension: `MethodInterceptor`, `ContainerObserver`, `ScopeProtocol`, `ConfigSource`, `TreeSource`.
+
+### ⚠️ Breaking Changes
+
+* Complete redesign compared to any prior internal/unreleased versions. APIs are not backward compatible.
+* Requires Python 3.10+.
+
+### 📚 Docs
+
+* Established new documentation structure including ADRs, Architecture, User Guide, Advanced Features, Cookbook, Integrations, and API Reference.
+
+### 🧪 Testing
+
+* Added comprehensive test suite covering core features, async behavior, AOP, configuration, scopes, and error handling.
+* Introduced patterns for testing with overrides and profiles.
+
+---
+
+## [2.0.1] - 2025-10-25
+
+### Added ✨
+
+- **ADR-0009: Flexible `@provides` Support**  
+  Implemented support for using `@provides` in additional contexts:
+  - `@staticmethod` methods within `@factory` classes  
+  - `@classmethod` methods within `@factory` classes  
+  - Module-level functions  
+  These new provider types are discovered automatically during module scanning and participate fully in dependency resolution, validation, and graph generation.
+
+- **Dependency Graph and Validation Enhancements**  
+  - `_build_resolution_graph` now includes edges for all `@provides` functions, regardless of where they are defined.  
+  - Fail-fast validation checks now cover static/class/module-level providers, reporting missing bindings consistently.  
+  - Scope inference and promotion logic apply equally to these new provider types.
+
+### Documentation 📚
+
+- Expanded `docs/overview.md` to document the new flexible provider options (`@staticmethod`, `@classmethod`, module-level functions).  
+- Updated `docs/guide.md` with practical examples showing when to use each style of provider.  
+- Linked ADR-0009 for design rationale and migration guidance.
+
+### Notes 📝
+
+- This is a **minor feature release** introducing a major ergonomics improvement (ADR-0009).  
+- Fully backward compatible with existing factories, components, and configuration mechanisms.  
+- Encourages a lighter, more Pythonic style for simple provider declarations.
+
+
+---
+
+## [<2.0.0]
+
+* Internal development and prototyping phase. Basic dependency injection concepts established. Architecture significantly reworked for the v2.0.0 release.
+

pico_ioc-2.0.1/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 2.0.1
+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
+Provides-Extra: yaml
+Requires-Dist: PyYAML; extra == "yaml"
+Provides-Extra: graphviz
+Requires-Dist: graphviz; extra == "graphviz"
+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 **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`, `@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).
+
+---
+
+## 🚀 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                        |
+
+---
+
+## 🧩 Highlights (v2.0.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.
+
+---
+
+## 📦 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:**
+
+    ```bash
+    pip install pico-ioc[graphviz]
+    ```
+
+    (Requires the `graphviz` Python package and the Graphviz command-line tools)
+
+-----
+
+## ⚙️ Quick Example
+
+```python
+from dataclasses import dataclass
+from pico_ioc import component, configuration, init
+
+@configuration
+@dataclass
+class Config:
+    db_url: str = "sqlite:///demo.db"
+
+@component
+class Repo:
+    def __init__(self, cfg: Config):
+        self.cfg = cfg
+    def fetch(self):
+        return f"fetching from {self.cfg.db_url}"
+
+@component
+class Service:
+    def __init__(self, repo: Repo):
+        self.repo = repo
+    def run(self):
+        return self.repo.fetch()
+
+container = init(modules=[__name__])
+svc = container.get(Service)
+print(svc.run())
+```
+
+**Output:**
+
+```
+fetching from sqlite:///demo.db
+```
+
+-----
+
+## 🧪 Testing with Overrides
+
+```python
+class FakeRepo:
+    def fetch(self): return "fake-data"
+
+container = init(modules=[__name__], overrides={Repo: FakeRepo()})
+svc = container.get(Service)
+assert svc.run() == "fake-data"
+```
+
+-----
+
+## 🩺 Lifecycle & AOP
+
+```python
+from pico_ioc import intercepted_by, MethodInterceptor, MethodCtx
+
+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
+
+@component
+class Demo:
+    @intercepted_by(LogInterceptor)
+    def work(self):
+        return "ok"
+
+c = init(modules=[__name__])
+c.get(Demo).work()
+```
+
+-----
+
+## 📖 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) — *Full redesign for v2.0.0.*
+
+-----
+
+## 📜 License
+
+MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

pico_ioc-2.0.1/README.md

@@ -0,0 +1,193 @@
+# 📦 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`, `@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).
+
+---
+
+## 🚀 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                        |
+
+---
+
+## 🧩 Highlights (v2.0.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.
+
+---
+
+## 📦 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:**
+
+    ```bash
+    pip install pico-ioc[graphviz]
+    ```
+
+    (Requires the `graphviz` Python package and the Graphviz command-line tools)
+
+-----
+
+## ⚙️ Quick Example
+
+```python
+from dataclasses import dataclass
+from pico_ioc import component, configuration, init
+
+@configuration
+@dataclass
+class Config:
+    db_url: str = "sqlite:///demo.db"
+
+@component
+class Repo:
+    def __init__(self, cfg: Config):
+        self.cfg = cfg
+    def fetch(self):
+        return f"fetching from {self.cfg.db_url}"
+
+@component
+class Service:
+    def __init__(self, repo: Repo):
+        self.repo = repo
+    def run(self):
+        return self.repo.fetch()
+
+container = init(modules=[__name__])
+svc = container.get(Service)
+print(svc.run())
+```
+
+**Output:**
+
+```
+fetching from sqlite:///demo.db
+```
+
+-----
+
+## 🧪 Testing with Overrides
+
+```python
+class FakeRepo:
+    def fetch(self): return "fake-data"
+
+container = init(modules=[__name__], overrides={Repo: FakeRepo()})
+svc = container.get(Service)
+assert svc.run() == "fake-data"
+```
+
+-----
+
+## 🩺 Lifecycle & AOP
+
+```python
+from pico_ioc import intercepted_by, MethodInterceptor, MethodCtx
+
+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
+
+@component
+class Demo:
+    @intercepted_by(LogInterceptor)
+    def work(self):
+        return "ok"
+
+c = init(modules=[__name__])
+c.get(Demo).work()
+```
+
+-----
+
+## 📖 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) — *Full redesign for v2.0.0.*
+
+-----
+
+## 📜 License
+
+MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

pico_ioc-2.0.1/docs/README.md

@@ -0,0 +1,89 @@
+# 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
+
+| Section | Focus | Start Here |
+| :--- | :--- | :--- |
+| **1. Getting Started** | Installation and 5-minute quick start. | [Quick Start](./getting-started.md) |
+| **2. User Guide** | Core concepts, configuration, scopes, and testing. | [User Guide Overview](./user-guide/README.md) |
+| **3. Advanced Features** | Async, AOP, Event Bus, and conditional logic. | [Advanced Features Overview](./advanced-features/README.md) |
+| **4. Observability** | Context, metrics, tracing, and graph export. | [Observability Overview](./observability/README.md) |
+| **5. Integrations** | FastAPI, Flask, Django, and AI/LangChain recipes. | [Integrations Overview](./integrations/README.md) |
+| **6. Cookbook (Patterns)** | Full architectural solutions (Multi-tenant, Hot-reload, CQRS). | [Cookbook Overview](./cookbook/README.md) |
+| **7. Architecture** | Design principles and internal deep-dive. | [Architecture Overview](./architecture/README.md) |
+| **8. API Reference** | Glossary and decorator/method cheatsheets. | [API Reference Overview](./api-reference/README.md) |
+
+
+## Overview
+
+**Pico IOC** is a Dependency Injection (DI) container for Python that implements advanced enterprise architecture patterns. Its design is inspired by frameworks like Spring (Java) and Guice, adapted for the Python ecosystem.
+
+It provides a robust, type-safe, and testable foundation for complex applications by managing component lifecycles, configuration, and runtime dependencies.
+
+---
+
+## Core Strengths
+
+The framework is built on specific principles:
+
+* **Fail-Fast at Startup:** All wiring errors are detected during `init()`, preventing runtime surprises.
+* **Async-Native:** Full integration of `async`/`await` across the resolution and lifecycle systems.
+* **AOP and Observability:** Built-in tools for cross-cutting concerns and monitoring runtime behavior.
+
+---
+
+## Getting Started: A Simple Example
+
+```python
+from dataclasses import dataclass
+from pico_ioc import component, init
+
+# 1. Define your components
+class Greeter:
+    def say_hello(self) -> str: ...
+
+@component
+class EnglishGreeter(Greeter):
+    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())
+
+# 3. Initialize the container
+# The 'modules' list tells pico_ioc where to scan for @component
+container = init(modules=[__name__])
+
+# 4. Get the root component and run
+app = container.get(App)
+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.1/docs/adr/README.md

@@ -0,0 +1,15 @@
+# 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-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

pico_ioc-2.0.1/docs/adr/adr-0001-async-native.md

@@ -0,0 +1,31 @@
+## ADR-001: Native Asyncio Support
+
+**Status:** Accepted
+
+### Context
+
+Modern Python web frameworks and I/O-bound applications heavily rely on `asyncio`. A synchronous DI container forces awkward workarounds (like running async initialization in `__init__` via `asyncio.run()`, which blocks) or cannot properly manage async resources. V1 lacked native support, hindering its use in async applications. We needed first-class `async`/`await` integration across the component lifecycle.
+
+### Decision
+
+We decided to make `pico-ioc` **async-native**. This involved several key changes:
+
+1.  Introduce `container.aget(key)` as the asynchronous counterpart to `container.get(key)`. `aget` correctly handles `await`ing async operations during resolution without blocking the event loop.
+2.  Support `async def` methods decorated with `@provides` within factories.
+3.  Introduce the `async def __ainit__(self, ...)` convention for components needing async initialization after `__init__`. Dependencies can be injected into `__ainit__`.
+4.  Allow `@configure` and `@cleanup` methods to be `async def`. A corresponding `container.cleanup_all_async()` method was added.
+5.  Ensure the AOP (`MethodInterceptor`) mechanism is async-aware, correctly `await`ing `call_next(ctx)` and allowing `async def invoke`.
+6.  Make the built-in `EventBus` fully asynchronous.
+
+### Consequences
+
+**Positive:** 👍
+* Seamless integration with `asyncio`-based applications (FastAPI, etc.).
+* Correct handling of async component initialization and cleanup without blocking.
+* Enables fully asynchronous AOP and event handling.
+* Improves developer experience for async projects.
+
+**Negative:** 👎
+* Introduces a dual API (`get`/`aget`), requiring developers to choose the correct one based on context.
+* Slightly increases internal complexity to manage async operations correctly.
+* Requires users to use `container.cleanup_all_async()` instead of `cleanup_all()` if any async cleanup methods exist.