pico-ioc 1.3.0__tar.gz → 2.1.2__tar.gz

{pico_ioc-1.3.0 → pico_ioc-2.1.2}/.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.1.2/.github/workflows/docs.yml

@@ -0,0 +1,104 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main, master ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [ main, master ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:
+
+permissions:
+  actions: read
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Validate documentation build
+        run: mkdocs build --strict
+
+      - name: Check for broken links (best-effort)
+        run: |
+          pip install linkchecker
+          python -m http.server --directory site 8000 &
+          sleep 3
+          linkchecker http://127.0.0.1:8000 --check-extern || true
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: |
+          mkdocs build --strict --verbose
+          echo "Built on $(date -u)" > site/build-info.txt
+          echo "Commit: ${{ github.sha }}" >> site/build-info.txt
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: './site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+      - name: Comment on commit (optional)
+        if: success()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.repos.createCommitComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: context.sha,
+              body: `✅ Documentation deployed successfully!\n\n📚 View at: ${'${{ steps.deployment.outputs.page_url }}'}`
+            })
+

pico_ioc-2.1.2/CHANGELOG.md

@@ -0,0 +1,222 @@
+# 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.1.1] - 2025-11-02
+
+### Added
+
+* ✨ Inline Field Overrides: Added support for overriding configuration fields directly in `@configured` classes using `Annotated[..., Value(...)]` (documented in ADR-0010).
+* Container Self-Injection: `PicoContainer` is now registered as a singleton and can be injected into other components.
+* Flexible `@provides`: `@provides` now supports module-level functions, `@staticmethod`, and `@classmethod` (ADR-0009), allowing for stateless providers without requiring a `@factory` instance.
+* New `websocket` Scope: Added a new default scope named `websocket` to the `ScopeManager`, based on `contextvars`.
+
+### Changed
+
+* Simplified `custom_scopes` API: `init(custom_scopes=...)` now accepts an `Iterable[str]` of scope names (instead of a dict), automatically registering them as `ContextVarScope`.
+* Strict Async Validation (Singletons): `init()` will now raise a `ConfigurationError` if a non-lazy (eager) singleton requires an async `@configure` method. This forces the developer to either use `aget()` or mark the component as `lazy=True`.
+* Async Validation (Other Scopes): Components with other scopes (e.g., `request`) that have an async `@configure` will now raise an `AsyncResolutionError` if retrieved with `get()` (sync) but will resolve correctly with `aget()` (async).
+
+### Fixed
+
+* EventBus Thread-Safety: Fixed a bug to ensure `EventBus.post()` is fully thread-safe and correctly handles the worker's event loop context.
+* Lazy Proxy and Async: The `UnifiedComponentProxy` (used for `lazy=True`) now correctly detects async `@configure` methods and raises an `AsyncResolutionError` if resolved synchronously.
+* Python Version: Updated `requires-python` to `>=3.10` to reflect actual dependencies (like `contextvars` and `typing.Annotated`) and prevent installation errors.
+* Internal Wiring: Cleaned up the import flow and internal logic in `api.init()` and `registrar.finalize()`.
+
+### Docs
+
+* User Guide & ADRs: Updated all documentation (User Guide, Glossary, ADRs) to reflect the unified configuration API (ADR-0010), removing all references to the old `@configuration` decorator.
+* API Reference: Updated the `init()` signature in `container.md` to show the change to `custom_scopes` and document the `validate_only` and `observers` parameters.
+* Simplified `architecture/comparison.md` and corrected minor errors.
+
+### Tests
+
+* Added `test_container_self_injection.py` to verify container self-injection.
+* Updated assertions in log and stats tests to reflect new eager initialization and scope semantics.
+
+---
+
+## [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-0010).
+* `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-0010).
+* 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-0010).
+
+### Removed ❌
+
+* `@configuration` Decorator: This decorator, previously used for flat key-value binding, has been completely removed in favor of the unified `@configured` decorator (ADR-0010).
+* 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-0010).
+
+---
+
+## [2.0.3] - 2025-10-26
+
+### Fixed
+
+- Injection now falls back from an annotated key to the parameter name when the annotated key is unbound, enabling resolution against string-key providers registered via `@provides("name")`.
+- `ProviderNotFoundError` includes the requesting origin (component or key) to aid debugging and test assertions.
+- Unified sync/async resolution path in `PicoContainer`:
+  - `get()` raises `AsyncResolutionError` if a provider returns an awaitable, guiding users to `aget()`.
+  - `aget()` awaits awaitables and applies aspects and caching consistently.
+  - Observers receive accurate resolve timings in both paths.
+
+### Added
+
+- `AsyncResolutionError` to signal misuse of `get()` when a provider is async.
+- More informative tracer notes for parameter binding.
+
+### Internal
+
+- `ComponentFactory.get()` now accepts an `origin` to enrich `ProviderNotFoundError` messages.
+- Lazy proxy creation calls `factory.get(key, origin="lazy")` to attribute provenance.
+- Public API exports updated to include `AsyncResolutionError`.
+
+### Compatibility
+
+- No public API breaking changes. Internal factory signature changed but remains encapsulated within the container/registrar.
+
+---
+
+## [2.0.2] - 2025-10-26
+
+### Fixed 🧩
+
+* `@provides` Decorator Execution
+  Corrected an issue where the `@provides` decorator executed its wrapped function prematurely during module import, leading to runtime errors like `TypeError: Service() takes no arguments`.
+  The decorator now properly registers provider metadata without invoking the function until dependency resolution time.
+
+### Added ✨
+
+* `FlatDictSource` Configuration Provider
+  Introduced a lightweight configuration source for flat in-memory dictionaries.
+  Supports optional key prefixing and case sensitivity control for simple, programmatic configuration injection.
+
+### Internal 🔧
+
+* Updated type imports and registration logic in `api.py` to support `Mapping` for the new configuration source.
+* Added `FlatDictSource` to the public API (`__all__` and import namespace).
+
+### Notes 📝
+
+* Fully backward compatible.
+* This patch release focuses on decorator correctness and configuration flexibility improvements.
+
+---
+
+## [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] - 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-0001).
+* 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-0002).
+* Context-Aware Scopes: Implemented `contextvars`-based scopes (e.g., `"request"`, `"session"`) for managing component lifecycles tied to specific contexts (ADR-0003).
+* Observability Features: Integrated container context (`container_id`, `as_current`), basic stats (`container.stats()`), observer protocol (`ContainerObserver`), and dependency graph export (`container.export_graph()`) (ADR-0004).
+* Aspect-Oriented Programming (AOP): Implemented method interception via `MethodInterceptor` protocol and `@intercepted_by` decorator, using a dynamic proxy (`UnifiedComponentProxy`) (ADR-0005).
+* Eager Startup Validation: Added fail-fast validation during `init()` to detect missing dependencies and configuration errors before runtime (ADR-0006).
+* Built-in Event Bus: Included an asynchronous, in-process event bus (`EventBus`, `@subscribe`, `AutoSubscriberMixin`) for decoupled communication (ADR-0007).
+* Explicit Circular Dependency Handling: Implemented detection and fail-fast for circular dependencies, requiring explicit resolution patterns (ADR-0008).
+* Unified Decorator API: Consolidated component metadata into parameterized decorators (`@component`, `@factory`, `@provides`), removing older stacked decorators (ADR-0009).
+
+### ✨ 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.0]
+
+* Internal development and prototyping phase. Basic dependency injection concepts established. Architecture significantly reworked for the v2.0.0 release.
+
+
+---

pico_ioc-2.1.2/PKG-INFO

@@ -0,0 +1,352 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 2.1.2
+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.10
+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)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pico-ioc?period=monthly&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=Monthly+downloads)](https://pepy.tech/projects/pico-ioc)
+[![Docs](https://img.shields.io/badge/Docs-pico--ioc-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-ioc/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/learn-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
+```
+
+Optional extras:
+
+- YAML configuration support (requires PyYAML)
+
+  ```bash
+  pip install pico-ioc[yaml]
+  ```
+
+-----
+
+## ⚙️ 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"
+```
+
+-----
+
+## 🧰 Profiles
+
+Use profiles to enable/disable components or configuration branches conditionally.
+
+```python
+# Enable "test" profile when bootstrapping the container
+container = init(
+    modules=[__name__],
+    profiles=["test"]
+)
+```
+
+Profiles are typically referenced in decorators or configuration mappings to include/exclude components and bindings.
+
+-----
+
+## ⚡ Async Components
+
+Pico-IoC supports async lifecycle and resolution.
+
+```python
+import asyncio
+from pico_ioc import component, init
+
+@component
+class AsyncRepo:
+    async def __ainit__(self):
+        # e.g., open async connections
+        self.ready = True
+
+    async def fetch(self):
+        return "async-data"
+
+async def main():
+    container = init(modules=[__name__])
+    repo = await container.aget(AsyncRepo)   # Async resolution
+    print(await repo.fetch())
+
+asyncio.run(main())
+```
+
+- `__ainit__` runs after construction if defined.
+- Use `container.aget(Type)` to resolve components that require async initialization or whose providers are async.
+
+-----
+
+## 🩺 Lifecycle & AOP
+
+```python
+import time
+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
+```
+
+-----
+
+## 👁️ Observability & Cleanup
+
+- Export a dependency graph in DOT format:
+
+  ```python
+  c = init(modules=[...])
+  dot = c.export_graph()  # Returns DOT graph as a string
+  with open("dependencies.dot", "w") as f:
+      f.write(dot)
+  ```
+
+- Health checks:
+  - Annotate health probes inside components with `@health` for container-level reporting.
+  - The container exposes health information that can be queried in observability tooling.
+
+- Container cleanup:
+  - For sync components: `container.close()`
+  - For async components/resources: `await container.aclose()`
+
+Use cleanup in application shutdown hooks to release resources deterministically.
+
+-----
+
+## 📖 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`
+- 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)