pico-ioc 2.0.5__tar.gz → 2.1.1__tar.gz

{pico_ioc-2.0.5 → pico_ioc-2.1.1}/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.h
 
 ---
 
+## [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-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
 
 ### Fixed

{pico_ioc-2.0.5 → pico_ioc-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.0.5
+Version: 2.1.1
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -39,7 +39,7 @@ 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
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: yaml
@@ -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.1/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)
+