pico-ioc 2.1.3__tar.gz → 2.2.1__tar.gz

{pico_ioc-2.1.3 → pico_ioc-2.2.1}/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to Semantic Versioning (https://semver.org/spec/v2.0.ht
 
 ---
 
+## [2.2.1] - 2026-02-03
+
+### Fixed 🧩
+
+- **DOT Graph Export**: Fixed incorrect variable reference in `export_graph()` where dependency edges used `{child}` instead of `{cid}`, causing malformed DOT output when visualizing the dependency graph.
+- **Race Condition in Lazy Proxy**: Fixed a race condition in `UnifiedComponentProxy._async_init_if_needed()` where concurrent async access could trigger duplicate object creation. The fix implements proper double-check locking and moves `@configure` execution outside the critical section to prevent deadlocks.
+- **Silent Cleanup Failures**: Replaced silent `except Exception: pass` blocks in `ScopedCaches` cleanup methods with proper logging. Cleanup method failures are now logged at WARNING level, aiding debugging of resource leaks without crashing the application.
+
+### Internal 🔧
+
+- Added `logging` import and `_logger` instance to `scope.py` for structured error reporting during component cleanup.
+
+---
+
+## [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

pico_ioc-2.2.1/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.3 → pico_ioc-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.1.3
+Version: 2.2.1
 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,20 +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 for v2.1.3+
+### ⚠️ Important Note
+
+**Breaking Behavior in Scope Management (v2.1.3+):**
+**Scope LRU Eviction has been removed** to guarantee data integrity.
 
-**Breaking Behavior in Custom Integrations:**
-As of version 2.1.3, **Scope LRU Eviction has been removed** to guarantee data integrity under high load.
-* **If you use `pico-fastapi`:** You are safe (the middleware handles cleanup automatically).
-* **If you perform manual scope management:** You **must** explicitly call `container._caches.cleanup_scope("scope_name", scope_id)` when a context ends. Failing to do so will result in a memory leak, as scopes are no longer automatically discarded when the container fills up.
+  * **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.
 
 -----
 
@@ -247,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.
 
 -----
 
@@ -292,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=[...])
+    c.export_graph("dependencies.dot")  # Writes directly to file
+    ```
 
-  ```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:
 
-- 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.
+      - 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()`
+  - Container cleanup:
+
+      - For sync apps: `container.shutdown()`
+      - For async apps: `await container.ashutdown()`
 
 Use cleanup in application shutdown hooks to release resources deterministically.
 
@@ -330,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`
 
 -----
 
@@ -359,3 +354,4 @@ See [CHANGELOG.md](./CHANGELOG.md) — Significant redesigns and features in v2.
 ## 📜 License
 
 MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

{pico_ioc-2.1.3 → pico_ioc-2.2.1}/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,20 +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 for v2.1.3+
+### ⚠️ Important Note
+
+**Breaking Behavior in Scope Management (v2.1.3+):**
+**Scope LRU Eviction has been removed** to guarantee data integrity.
 
-**Breaking Behavior in Custom Integrations:**
-As of version 2.1.3, **Scope LRU Eviction has been removed** to guarantee data integrity under high load.
-* **If you use `pico-fastapi`:** You are safe (the middleware handles cleanup automatically).
-* **If you perform manual scope management:** You **must** explicitly call `container._caches.cleanup_scope("scope_name", scope_id)` when a context ends. Failing to do so will result in a memory leak, as scopes are no longer automatically discarded when the container fills up.
+  * **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.
 
 -----
 
@@ -197,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.
 
 -----
 
@@ -242,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=[...])
+    c.export_graph("dependencies.dot")  # Writes directly to file
+    ```
 
-  ```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:
 
-- 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.
+      - 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()`
+  - Container cleanup:
+
+      - For sync apps: `container.shutdown()`
+      - For async apps: `await container.ashutdown()`
 
 Use cleanup in application shutdown hooks to release resources deterministically.
 
@@ -280,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`
 
 -----
 
@@ -309,3 +304,4 @@ See [CHANGELOG.md](./CHANGELOG.md) — Significant redesigns and features in v2.
 ## 📜 License
 
 MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

pico_ioc-2.2.1/docs/README.md

@@ -0,0 +1,142 @@
+# Pico-IoC Documentation
+
+`pico-ioc` is a lightweight, async-native Inversion of Control (IoC) container for Python 3.10+. It brings enterprise-grade dependency injection, configuration binding, and AOP to the Python ecosystem.
+
+---
+
+## Quick Install
+
+```bash
+pip install pico-ioc
+
+# Optional: YAML configuration support
+pip install pico-ioc[yaml]
+```
+
+---
+
+## 30-Second Example
+
+```python
+from pico_ioc import component, init
+
+@component
+class Database:
+    def query(self) -> str:
+        return "data from DB"
+
+@component
+class UserService:
+    def __init__(self, db: Database):  # Auto-injected
+        self.db = db
+
+    def get_users(self) -> str:
+        return self.db.query()
+
+# Initialize and use
+container = init(modules=[__name__])
+service = container.get(UserService)
+print(service.get_users())  # "data from DB"
+```
+
+---
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Async-Native** | Full `async`/`await` support: `aget()`, `__ainit__`, async `@cleanup` |
+| **Unified Configuration** | `@configured` maps ENV vars or YAML/JSON to dataclasses |
+| **Fail-Fast Validation** | All wiring errors detected at `init()`, not runtime |
+| **AOP Interceptors** | `@intercepted_by` for logging, caching, security |
+| **Scoped Lifecycles** | singleton, prototype, request, session, transaction |
+| **Observable** | Built-in stats, health checks, dependency graph export |
+
+---
+
+## Documentation Structure
+
+| # | Section | Description | Link |
+|---|---------|-------------|------|
+| 1 | **Getting Started** | 5-minute tutorial | [getting-started.md](./getting-started.md) |
+| 2 | **User Guide** | Core concepts, configuration, scopes, testing | [user-guide/](./user-guide/README.md) |
+| 3 | **Advanced Features** | Async, AOP, Event Bus, conditional binding | [advanced-features/](./advanced-features/README.md) |
+| 4 | **Observability** | Metrics, tracing, graph export | [observability/](./observability/README.md) |
+| 5 | **Cookbook** | Real-world patterns (multi-tenant, CQRS, etc.) | [cookbook/](./cookbook/README.md) |
+| 6 | **Architecture** | Design principles, internals | [architecture/](./architecture/README.md) |
+| 7 | **API Reference** | Decorators, exceptions, protocols | [api-reference/](./api-reference/README.md) |
+| 8 | **FAQ** | Common questions and solutions | [faq.md](./faq.md) |
+| 9 | **Examples** | Complete runnable applications | [examples/](./examples/README.md) |
+
+---
+
+## Core APIs at a Glance
+
+### Registration
+
+```python
+from pico_ioc import component, factory, provides
+
+@component                    # Register a class
+class MyService: ...
+
+@factory                      # Group related providers
+class ClientFactory:
+    @provides(RedisClient)    # Provide third-party types
+    def build_redis(self, config: RedisConfig) -> RedisClient:
+        return RedisClient(config.url)
+```
+
+### Configuration
+
+```python
+from dataclasses import dataclass
+from pico_ioc import configured, configuration, init
+
+@configured(prefix="DB_")
+@dataclass
+class DBConfig:
+    host: str = "localhost"
+    port: int = 5432
+
+container = init(
+    modules=[__name__],
+    config=configuration()  # Reads from ENV: DB_HOST, DB_PORT
+)
+```
+
+### Async Support
+
+```python
+@component
+class AsyncService:
+    async def __ainit__(self):
+        self.conn = await open_connection()
+
+    @cleanup
+    async def close(self):
+        await self.conn.close()
+
+# Resolve async components
+service = await container.aget(AsyncService)
+
+# Cleanup
+await container.ashutdown()
+```
+
+### Testing with Overrides
+
+```python
+container = init(
+    modules=[__name__],
+    overrides={Database: FakeDatabase()}  # Replace for tests
+)
+```
+
+---
+
+## Next Steps
+
+1. **New to pico-ioc?** Start with the [Getting Started](./getting-started.md) tutorial
+2. **Coming from Spring/Guice?** Check the [Architecture Comparison](./architecture/comparison.md)
+3. **Building a real app?** See the [Cookbook](./cookbook/README.md) patterns

{pico_ioc-2.1.3 → pico_ioc-2.2.1}/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.2.1/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.3 → pico_ioc-2.2.1}/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) 🔎
 
 ---