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

{pico_ioc-2.1.2 → pico_ioc-2.2.0}/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to Semantic Versioning (https://semver.org/spec/v2.0.ht
 
 ---
 
+## [2.2.0] - 2025-11-29
+
+### Added ✨
+- **Extensible Component Scanning (ADR-0011):** Introduced the `CustomScanner` protocol and `custom_scanners` parameter in `init()`. This opens the discovery phase to third-party extensions, allowing registration of components based on custom decorators or base classes.
+- **Function-First Scanning:** Updated `ComponentScanner` to evaluate `CustomScanner` logic against *all* module members (classes and functions) before applying native logic. This enables extensions to register standalone functions (e.g., `@task`) as components.
+- **Async Shutdown:** Added `container.ashutdown()` (awaitable). This fills a critical gap in the async lifecycle, ensuring that `async def @cleanup` methods are properly awaited during application teardown.
+
+### Changed
+- **Internal Cleanup:** Removed the deprecated `max_scopes_per_type` parameter from `ScopedCaches`, reflecting the removal of LRU eviction in v2.1.3.
+
+### Docs 📚
+- **Major Restructuring:** Rebuilt `mkdocs.yml` navigation to include all available documentation pages.
+- **New Content:** Added missing guides for **Integrations** (Celery), **Advanced Features** (Self-Injection, AOP Proxies, Custom Scanners), and **Architecture** (Runtime Model).
+- **Corrections:** Fixed discrepancies in asset filenames (`extra.js`) and standardized the format of Architecture Decision Records (ADRs).
+
+---
+
+## [2.1.3] - 2025-11-18
+
+### Fixed
+- **Critical:** Removed unsafe LRU eviction in `ScopedCaches`. Previously, under high concurrency (e.g., >2048 requests/websockets), active scopes could be evicted, causing data loss and premature cleanup. Scopes now persist until explicitly cleaned up.
+- **Critical:** Fixed a race condition in `UnifiedComponentProxy` (AOP) where the underlying object creation wasn't fully thread-safe.
+- **Critical:** Fixed a race condition in `EventBus.post()` where the queue reference could be lost during shutdown.
+- **Critical:** Fixed `ScopeManager` returning a bucket for `None` IDs, which could cause state leakage between threads/tasks outside of an active context. Now raises `ScopeError`.
+- Fixed `AsyncResolutionError` when accessing `lazy=True` components that require asynchronous `@configure` methods. `aget()` now hydrates proxies immediately if needed.
+- Fixed a swallowed exception in `analyze_callable_dependencies` that hid configuration errors. Now logs debug information.
+- Fixed recursion error in `UnifiedComponentProxy.__setattr__` when setting internal attributes.
+
+### Changed
+- **Breaking Behavior:** Users using `pico-fastapi` or manual scope management **must** ensure `container.cleanup_scope(...)` is called at the end of the lifecycle to prevent memory leaks, as the automatic LRU safety net has been removed in favor of data integrity.
+- Improved integer configuration parsing to support formats like `1_000` or scientific notation in `config_runtime.py`.
+- `init()` now fails fast with an `AsyncResolutionError` if a component returns an awaitable from a synchronous `@configure` method, instead of just logging a warning.
+
+### Added
+- Architectural support for asynchronous hydration of lazy proxies via `_async_init_if_needed`.
+
+---
+
+## [2.1.2] - 2025-11-10
+
+### Added ✨
+
+* **Collection & Mapping Injection:** Constructors can now request collection-like dependencies and dictionaries:
+
+  * Supported collection origins: `List`, `Set`, `Iterable`, `Sequence`, `Collection`, `Deque` (resolved as concrete **lists** at injection time).
+  * Supported mappings: `Dict[K, V]` / `Mapping[K, V]` where `K ∈ {str, type, Any}` and `V` is a component/protocol.
+  * `Annotated[..., Qualifier("q")]` on the element type is honored for both collections and dict values.
+* **Element-type analysis for dicts:** Dependency analysis records the dict key type and value element type for correct resolution.
+
+### Changed
+
+* **Analyzer:** `analyze_callable_dependencies` now recognizes a broader set of `collections.abc` origins for collections and supports dict/mapping shapes, including qualifier propagation from `Annotated` element types.
+* **Container:** Dictionary injection computes keys from component metadata:
+
+  * `Dict[str, V]` → uses `pico_name` (or string key/fallback to class `__name__`).
+  * `Dict[type, V]` → uses the concrete class (or provided type).
+  * `Dict[Any, V]` → chooses sensible defaults (`pico_name` → string key → class name).
+* **Type imports & internals:** Expanded typing/runtime imports to support the new analysis and resolution paths.
+
+### Fixed 🧩
+
+* **Protocol matching:** `ComponentLocator` now checks attribute presence (including annotated attributes), reducing false positives when matching `Protocol` types.
+* **Resolution guard:** `_resolve_args` safely no-ops when the locator is unavailable, avoiding edge-case errors during early initialization.
+
+### Docs 📚
+
+* **README:** Removed the deprecated *Integrations* entry from the docs index.
+* **Architecture:** Corrected ADR links to `../adr/README.md` and references to the ADR workflow.
+
+### Tests 🧪
+
+* **New:** `tests/test_collection_injection.py` covering:
+
+  * Analyzer plans for collections/dicts (including qualifiers).
+  * Container resolution of lists/sets/iterables/sequences/deques as lists.
+  * Dictionary injection for `Dict[str, V]` and `Dict[type, V]`.
+
+---
+
 ## [2.1.1] - 2025-11-02
 
 ### Added

pico_ioc-2.2.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include LICENSE
+
+recursive-include src *.py
+
+recursive-include tests *.py
+
+exclude .gitignore
+exclude Dockerfile*
+exclude docker-compose*.yml
+exclude Makefile
+
+prune build
+prune dist
+prune .tox
+prune .pytest_cache
+prune __pycache__
+

{pico_ioc-2.1.2/src/pico_ioc.egg-info → pico_ioc-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.1.2
+Version: 2.2.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -28,7 +28,7 @@ License: MIT License
 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
+Keywords: python,ioc,dependency-injection,di-container,inversion-of-control,ioc-container,zero-dependency,minimalistic,async,asyncio,modular,pluggable,ioc-framework,ioc-containers,inversion-of-control-container
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -62,7 +62,6 @@ Dynamic: license-file
 [![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.
 
@@ -97,14 +96,14 @@ Pico-IoC eliminates that friction by letting you declare how components relate
 
 ---
 
-## 🧩 Highlights (v2.0+)
+## 🧩 Highlights (v2.2+)
 
-- 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.
+- **Unified Configuration**: Use `@configured` to bind both flat (ENV-like) and tree (YAML/JSON) sources via the `configuration(...)` builder (ADR-0010).
+- **Extensible Scanning**: Use `CustomScanner` to hook into the discovery phase and register functions or custom decorators (ADR-0011).
+- **Async-aware AOP**: Method interceptors via `@intercepted_by`.
+- **Scoped resolution**: singleton, prototype, request, session, transaction, and custom scopes.
+- **Tree-based configuration**: Advanced mapping with reusable adapters (`Annotated[Union[...], Discriminator(...)]`).
+- **Observable context**: Built-in stats, health checks (`@health`), observer hooks (`ContainerObserver`), and dependency graph export.
 
 ---
 
@@ -116,11 +115,21 @@ pip install pico-ioc
 
 Optional extras:
 
-- YAML configuration support (requires PyYAML)
+  - YAML configuration support (requires PyYAML)
 
-  ```bash
-  pip install pico-ioc[yaml]
-  ```
+    ```bash
+    pip install pico-ioc[yaml]
+    ```
+
+-----
+
+### ⚠️ Important Note
+
+**Breaking Behavior in Scope Management (v2.1.3+):**
+**Scope LRU Eviction has been removed** to guarantee data integrity.
+
+  * **Frameworks (pico-fastapi):** Handled automatically.
+  * **Manual usage:** You **must** explicitly call `container._caches.cleanup_scope("scope_name", scope_id)` when a context ends to prevent memory leaks.
 
 -----
 
@@ -238,12 +247,16 @@ async def main():
     container = init(modules=[__name__])
     repo = await container.aget(AsyncRepo)   # Async resolution
     print(await repo.fetch())
+    
+    # Graceful async shutdown (calls @cleanup async methods)
+    await container.ashutdown()
 
 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.
+  - `__ainit__` runs after construction if defined.
+  - Use `container.aget(Type)` to resolve components that require async initialization.
+  - Use `await container.ashutdown()` to close resources cleanly.
 
 -----
 
@@ -283,35 +296,26 @@ 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:
+  - 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)
-  ```
+    ```python
+    c = init(modules=[...])
+    c.export_graph("dependencies.dot")  # Writes directly to file
+    ```
 
-- 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.
+  - Health checks:
 
-- Container cleanup:
-  - For sync components: `container.close()`
-  - For async components/resources: `await container.aclose()`
+      - 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 apps: `container.shutdown()`
+      - For async apps: `await container.ashutdown()`
 
 Use cleanup in application shutdown hooks to release resources deterministically.
 
@@ -321,14 +325,14 @@ Use cleanup in application shutdown hooks to release resources deterministically
 
 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`
+  - 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`
 
 -----
 
@@ -343,10 +347,11 @@ tox
 
 ## 🧾 Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) — Significant redesigns and features in v2.0+.
+See [CHANGELOG.md](https://www.google.com/search?q=./CHANGELOG.md) — Significant redesigns and features in v2.0+.
 
 -----
 
 ## 📜 License
 
 MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

{pico_ioc-2.1.2 → pico_ioc-2.2.0}/README.md

@@ -12,7 +12,6 @@
 [![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.
 
@@ -47,14 +46,14 @@ Pico-IoC eliminates that friction by letting you declare how components relate
 
 ---
 
-## 🧩 Highlights (v2.0+)
+## 🧩 Highlights (v2.2+)
 
-- 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.
+- **Unified Configuration**: Use `@configured` to bind both flat (ENV-like) and tree (YAML/JSON) sources via the `configuration(...)` builder (ADR-0010).
+- **Extensible Scanning**: Use `CustomScanner` to hook into the discovery phase and register functions or custom decorators (ADR-0011).
+- **Async-aware AOP**: Method interceptors via `@intercepted_by`.
+- **Scoped resolution**: singleton, prototype, request, session, transaction, and custom scopes.
+- **Tree-based configuration**: Advanced mapping with reusable adapters (`Annotated[Union[...], Discriminator(...)]`).
+- **Observable context**: Built-in stats, health checks (`@health`), observer hooks (`ContainerObserver`), and dependency graph export.
 
 ---
 
@@ -66,11 +65,21 @@ pip install pico-ioc
 
 Optional extras:
 
-- YAML configuration support (requires PyYAML)
+  - YAML configuration support (requires PyYAML)
 
-  ```bash
-  pip install pico-ioc[yaml]
-  ```
+    ```bash
+    pip install pico-ioc[yaml]
+    ```
+
+-----
+
+### ⚠️ Important Note
+
+**Breaking Behavior in Scope Management (v2.1.3+):**
+**Scope LRU Eviction has been removed** to guarantee data integrity.
+
+  * **Frameworks (pico-fastapi):** Handled automatically.
+  * **Manual usage:** You **must** explicitly call `container._caches.cleanup_scope("scope_name", scope_id)` when a context ends to prevent memory leaks.
 
 -----
 
@@ -188,12 +197,16 @@ async def main():
     container = init(modules=[__name__])
     repo = await container.aget(AsyncRepo)   # Async resolution
     print(await repo.fetch())
+    
+    # Graceful async shutdown (calls @cleanup async methods)
+    await container.ashutdown()
 
 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.
+  - `__ainit__` runs after construction if defined.
+  - Use `container.aget(Type)` to resolve components that require async initialization.
+  - Use `await container.ashutdown()` to close resources cleanly.
 
 -----
 
@@ -233,35 +246,26 @@ 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:
+  - 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)
-  ```
+    ```python
+    c = init(modules=[...])
+    c.export_graph("dependencies.dot")  # Writes directly to file
+    ```
 
-- 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.
+  - Health checks:
 
-- Container cleanup:
-  - For sync components: `container.close()`
-  - For async components/resources: `await container.aclose()`
+      - 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 apps: `container.shutdown()`
+      - For async apps: `await container.ashutdown()`
 
 Use cleanup in application shutdown hooks to release resources deterministically.
 
@@ -271,14 +275,14 @@ Use cleanup in application shutdown hooks to release resources deterministically
 
 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`
+  - 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`
 
 -----
 
@@ -293,10 +297,11 @@ tox
 
 ## 🧾 Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) — Significant redesigns and features in v2.0+.
+See [CHANGELOG.md](https://www.google.com/search?q=./CHANGELOG.md) — Significant redesigns and features in v2.0+.
 
 -----
 
 ## 📜 License
 
 MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

{pico_ioc-2.1.2 → pico_ioc-2.2.0}/docs/adr/README.md

@@ -13,6 +13,7 @@ ADR Index:
 - ADR-008: Explicit Handling of Circular Dependencies — Accepted — ./adr-0008-circular-dependencies.md
 - ADR-009: Flexible @provides for Static and Module-level Functions — Accepted — ./adr-0009-flexible-provides.md
 - ADR-010: Unified Configuration via @configured and ContextConfig — Accepted — ./adr-0010-unified-configuration.md
+- ADR-011: Extensible Component Scanning via Custom Scanners — Accepted — ./adr-0011-custom-scanners.md
 
 Status legend:
 - Proposed: Under discussion, not yet binding.

{pico_ioc-2.1.2 → pico_ioc-2.2.0}/docs/adr/adr-0002-tree-based-configuration.md

@@ -1,6 +1,7 @@
 # ADR-002: Tree-Based Configuration Binding
 
-Status: Accepted (Partially Superseded by ADR-0010)
+> ⚠️ **DEPRECATED**: This decision has been superseded by ADR-010 (Unified Configuration). 
+> This document is kept for historical context only. Please refer to the User Guide.
 
 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.
 

pico_ioc-2.2.0/docs/adr/adr-0003-context-aware-scopes.md

@@ -0,0 +1,107 @@
+# ADR-003: Context-Aware Scopes
+
+Status: Accepted
+
+## Update (v2.1.3) - Removal of LRU
+
+The original decision to use LRU (Least Recently Used) eviction for scoped caches (see point 5 below) proved unsafe for high-concurrency scenarios, such as WebSockets or long-polling. In these cases, active but "quiet" connections could be arbitrarily evicted when the container reached its limit, causing data loss (amnesia) for ongoing sessions.
+
+**Decision:** The LRU logic was removed in version 2.1.3.
+**New Behavior:** Scoped caches are now unbounded to guarantee data integrity for all active contexts.
+**Requirement:** Integrators (e.g., web middleware or manual context managers) **must** explicitly call `container._caches.cleanup_scope(...)` at the end of the lifecycle to prevent memory leaks.
+
+---
+
+### Context
+
+Many applications, especially web services, need components whose lifecycle is tied to a specific context, like an individual HTTP request or a user's session. Imagine needing a unique `UserContext` object for each logged-in user making requests simultaneously. The standard `singleton` (one instance forever) and `prototype` (new instance every time) scopes aren't suitable for managing state within these temporary contexts. We needed a way to create "scoped singletons" – ensuring exactly one instance per active context.
+
+### Decision
+
+We introduced context-aware scopes built upon Python's `contextvars`:
+
+1) **ScopeProtocol:** Defined a minimal interface for custom scope implementations, requiring only `get_id() -> Any | None` to return the identifier of the currently active scope instance.
+
+2) **ContextVarScope:** Provided a standard implementation using `contextvars.ContextVar`. This allows tracking the active scope ID within async tasks and threads correctly. It includes helper methods like `activate(id)` and `deactivate(token)`.
+
+3) **ScopeManager:** An internal registry holding `ScopeProtocol` implementations for named scopes (e.g., "request", "session"). It provides the core logic for activating, deactivating, and retrieving the current ID for any registered scope.
+
+4) **`scope="..."` parameter:** Components are assigned to a specific scope using the `scope` parameter within the main registration decorators (`@component`, `@factory`, `@provides`). For example: `@component(scope="request")`.
+
+5) **ScopedCaches:** Modified the internal caching mechanism to handle multiple caches keyed by `(scope_name, scope_id)`.
+   * *Historical Note:* Originally, this used an LRU strategy to automatically evict caches. As of v2.1.3, this is an unbounded registry requiring explicit cleanup.
+
+6) **Container API:** Added convenient methods for managing scopes:
+    - `container.activate_scope(name, id)` and `container.deactivate_scope(name, token)` for manual control.
+    - The preferred `with container.scope(name, id):` context manager for easy, safe activation and deactivation within a block.
+    - Pre-registered common web scopes like "request", "session", and "transaction" for convenience.
+
+### Usage
+
+- **Registering a scoped component:**
+  - Use `@component(scope="request")` to ensure one instance per active request scope.
+  - Factories and providers support scope in the same way: `@factory(scope="session")`, `@provides(scope="transaction")`.
+
+- **Activating a scope:**
+  - Prefer the context manager: `with container.scope("request", request_id):` resolve components and handle work inside the block.
+  - Manual control:
+    - `token = container.activate_scope("session", session_id)`
+    - ...resolve and use components...
+    - `container.deactivate_scope("session", token)`
+
+- **Custom scopes:**
+  - Define a custom scope by implementing `ScopeProtocol` (providing `get_id()`) or by using `ContextVarScope`.
+  - Register at initialization via `init(custom_scopes={"tenant": ContextVarScope(...)})`.
+  - Use `@component(scope="tenant")` for components that should be unique per tenant.
+
+- **Async compatibility:**
+  - Scopes rely on `contextvars`, so active scope IDs propagate correctly across `asyncio` tasks spawned within the same context.
+  - For thread pools or manual threading, activate the scope within each worker execution or ensure framework integration propagates context.
+
+### Implementation Notes
+
+- **Scope identifiers:**
+  - Scope IDs must be stable and hashable; they are used as part of the cache key (scope_name, scope_id).
+  - Choose IDs that uniquely represent the current context (e.g., a UUID for requests, a user/session ID for sessions).
+
+- **Cache management:**
+  - `ScopedCaches` maintains a distinct cache per `(scope_name, scope_id)` pairing.
+  - *Updated v2.1.3:* Cleanup is manual via `cleanup_scope`.
+
+- **Safety:**
+  - The context manager ensures scopes are correctly deactivated even if exceptions occur inside the block.
+  - Manual activate/deactivate requires pairing the token returned by `activate_scope` with `deactivate_scope` to avoid leaks.
+
+### Consequences
+
+**Positive:**
+- Enables safe and isolated management of context-specific state (e.g., holding data for a single web request without interfering with others).
+- Integrates naturally with `asyncio` due to the use of `contextvars`, making it suitable for modern async web frameworks.
+- Provides a clean and developer-friendly API for activating/deactivating scopes, especially the `with container.scope():` manager.
+- Extensible: Users can define and register their own custom scopes via `init(custom_scopes={...})`.
+
+**Negative:**
+- Relies on `contextvars`, which requires careful handling, especially regarding context propagation across thread boundaries if not managed automatically by frameworks.
+- Requires explicit scope activation/deactivation in the application's entry points (e.g., web middleware). The container itself doesn't automatically detect the start/end of a request; the framework integration needs to call the container's scope methods.
+- **Memory Management:** Without the automatic LRU (removed in v2.1.3), there is a risk of memory leaks if the integration layer fails to call `cleanup_scope` after the context ends.
+
+### Alternatives Considered
+
+- **Thread-local storage:**
+  - Rejected due to poor compatibility with `asyncio` and cross-thread propagation issues in modern Python web runtimes.
+
+- **Global registries keyed by request/session:**
+  - Rejected for complexity, manual cleanup requirements, and weaker isolation compared to `contextvars`.
+
+- **Prototype-only components:**
+  - Rejected because they cannot guarantee a single instance per context, leading to duplicated state and higher allocation overhead.
+
+### Migration
+
+- **Existing singleton components that should be per-request or per-session:**
+  - Add `scope="request"` or `scope="session"` to their registration decorators.
+  - Ensure the application activates the corresponding scope in middleware/entry points.
+
+- **Framework integration:**
+  - Web frameworks should activate the "request" scope at the start of request handling and deactivate it at the end.
+  - **Update:** Frameworks must also ensure `container._caches.cleanup_scope("request", id)` is called in a `finally` block.

pico_ioc-2.2.0/docs/adr/adr-0011-custom-scanners.md

@@ -0,0 +1,81 @@
+# ADR-0011: Extensible Component Scanning via Custom Scanners
+
+Status: Accepted
+
+## Context
+
+The original component scanning mechanism in `pico-ioc` was designed as a closed system. It strictly looked for specific internal decorators (`@component`, `@factory`, `@provides`, `@configured`) and hardcoded logic within `ComponentScanner`.
+
+This rigidity created significant challenges for third-party extensions (such as `pico-agent` or web frameworks):
+1.  **Global Mutable State:** Extensions were forced to use global registries (e.g., `_PENDING_AGENTS` lists) to track decorated objects, leading to thread-safety issues and test contamination.
+2.  **Fragile Hacks:** Extensions often relied on stack frame inspection to guess the caller's module, which is unreliable.
+3.  **Lack of Hooks:** There was no clean way to intercept the scanning phase to register objects based on custom logic (e.g., registering a function decorated with `@task` as a prototype component).
+
+We needed a standardized, stateless extension point to allow third-party libraries to participate in the discovery phase.
+
+## Decision
+
+We introduce the `CustomScanner` protocol and expose a new `custom_scanners` argument in the `init()` API.
+
+1.  **Protocol Definition:** We define a `CustomScanner` protocol with `should_scan(obj)` and `scan(obj)` methods. This delegates the responsibility of pattern matching and metadata construction to the extension author.
+2.  **Priority Scanning:** The `ComponentScanner` iteration logic is modified to prioritize these custom scanners.
+    * The scanner iterates through all module members once.
+    * For **every** member (whether it is a Class, Function, or other object), it first checks the registered `custom_scanners`.
+    * If a custom scanner claims the object (returns a binding), the built-in native scanning logic is skipped for that object.
+3.  **Injection via Init:** Users or frameworks pass instances of these scanners into the container via `init(..., custom_scanners=[...])`.
+
+## Details
+
+### The Protocol
+
+```python
+class CustomScanner(Protocol):
+    def should_scan(self, obj: Any) -> bool:
+        """Return True if this scanner handles the given object."""
+        ...
+
+    def scan(self, obj: Any) -> Optional[Tuple[KeyT, Provider, ProviderMetadata]]:
+        """
+        Constructs the binding artifacts.
+        Returns (key, provider, metadata) or None.
+        """
+        ...
+```
+
+### Scanning Logic
+
+The internal loop in `ComponentScanner.scan_module` effectively works as follows:
+
+```python
+for name, obj in inspect.getmembers(module):
+    # 1. Custom Scanners take precedence over everything
+    if self._try_custom_scanners(obj):
+        continue
+
+    # 2. Native logic (Component, Factory, Configured, Provides)
+    # ...
+```
+
+This ensures that a custom scanner can override default behavior or register objects that `pico-ioc` would normally ignore (like standalone functions decorated with custom markers).
+
+## Consequences
+
+### Positive
+
+  - **Decoupling:** Extensions no longer need to depend on `pico-ioc` internals or global state.
+  - **Flexibility:** Enables support for function-based components (e.g., tasks, agents) and custom class decorators.
+  - **Safety:** Scanners are scoped to the container instance, ensuring thread safety and isolation during tests.
+  - **Performance:** Single-pass iteration over module members allows for efficient discovery without repeated `inspect` calls.
+
+### Negative
+
+  - **Complexity:** Increases the API surface area of `init()`.
+  - **Manual Wiring:** Without a wrapper (like `pico-stack`), users must manually instantiate and pass scanner instances to `init()`.
+
+## Alternatives Considered
+
+  - **Global Registry Hooks:** Rejected due to testing isolation issues and "magic" global state.
+  - **Inheritance (`class MyScanner(ComponentScanner)`):** Rejected because it tightly couples extensions to the internal implementation of the default scanner and makes composing multiple extensions difficult.
+
+<!-- end list -->
+

{pico_ioc-2.1.2 → pico_ioc-2.2.0}/docs/advanced-features/README.md

@@ -11,6 +11,6 @@ Welcome to the Advanced Features guide. You've mastered the core concepts. This
 * [3. The Event Bus: `EventBus`, `@subscribe`](./event-bus.md) 📢
 * [4. Conditional Binding: `primary`, `on_missing_selector`, `conditional_*`](./conditional-binding.md) 🤔
 * [5. Health Checks: `@health`](./health-checks.md) ❤️‍🩹
-
+* [6. Custom Component Scanners](./custom-scanners.md) 🔎
 
 ---