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

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

@@ -7,6 +7,68 @@ and this project adheres to Semantic Versioning (https://semver.org/spec/v2.0.ht
 
 ---
 
+## [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.1.2/src/pico_ioc.egg-info → pico_ioc-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.1.2
+Version: 2.1.3
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -124,6 +124,15 @@ Optional extras:
 
 -----
 
+### ⚠️ Important Note for v2.1.3+
+
+**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.
+
+-----
+
 ## ⚙️ Quick Example (Unified Configuration)
 
 ```python

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

@@ -74,6 +74,15 @@ Optional extras:
 
 -----
 
+### ⚠️ Important Note for v2.1.3+
+
+**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.
+
+-----
+
 ## ⚙️ Quick Example (Unified Configuration)
 
 ```python

{pico_ioc-2.1.2 → pico_ioc-2.1.3}/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.1.3/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.1.3/docs/advanced-features/async-resolution.md

@@ -0,0 +1,465 @@
+# Advanced: Async Resolution (`aget`, `__ainit__`)
+
+Modern Python applications are increasingly built on `asyncio`. `pico-ioc` is async-native, meaning it fully supports asynchronous operations throughout the component lifecycle, from creation to cleanup.
+
+This guide covers how to:
+
+  * Resolve components asynchronously using `container.aget()`.
+  * Define components that require `await` during their creation.
+  * Use asynchronous lifecycle hooks like `@cleanup` and `@configure`.
+
+-----
+
+## 1\. `container.aget()`: The Async `get()`
+
+If you are in an `async` function, you should always use `container.aget()` instead of `container.get()`.
+
+  * `container.get()`: Synchronous. Blocks the event loop if a component needs to be created.
+  * `container.aget()`: Asynchronous. Properly awaits the creation of any async components, ensuring the event loop is never blocked.
+
+<!-- end list -->
+
+```python
+from pico_ioc import component, init
+
+@component
+class MyAsyncService:
+    ...
+
+async def main():
+    container = init(modules=[__name__])
+    
+    # Use .aget() inside an async function
+    service = await container.aget(MyAsyncService)
+    
+    # This would be bad! It could block.
+    # service = container.get(MyAsyncService)
+```
+
+-----
+
+## 2\. Asynchronous Component Creation
+
+Your components often need to perform I/O during their initialization (e.g., connect to a database, call an API). `pico-ioc` supports this in two primary ways.
+
+### Method 1: Async Factory (`async def @provides`)
+
+The cleanest way to create an async component is with a factory. You can decorate an `async def` method with `@provides`. `pico-ioc` will automatically await it when it's resolved via `container.aget()`.
+
+```python
+import asyncio
+from pico_ioc import component, factory, provides, init
+
+# A mock async database client
+class AsyncDatabase:
+    def __init__(self):
+        self.connected = True
+        print("Database connected")
+
+    @staticmethod
+    async def connect(url: str):
+        print(f"Connecting to {url}...")
+        await asyncio.sleep(0.01)  # Mock I/O
+        return AsyncDatabase()
+
+@factory
+class DatabaseFactory:
+    
+    # Use 'async def' with @provides
+    @provides(AsyncDatabase)
+    async def build_db(self) -> AsyncDatabase:
+        db = await AsyncDatabase.connect("postgres://...")
+        return db
+
+@component
+class UserService:
+    def __init__(self, db: AsyncDatabase):
+        self.db = db
+
+# --- In your main async function ---
+async def main():
+    container = init(modules=[__name__])
+    
+    # .aget() will correctly await the build_db() factory
+    user_service = await container.aget(UserService)
+    
+    assert user_service.db.connected is True
+
+# Output:
+# Connecting to postgres://...
+# Database connected
+```
+
+### Method 2: Async Constructor (`__ainit__`)
+
+You cannot make `__init__` an `async def` method in Python.
+
+To solve this, `pico-ioc` supports a special method: `__ainit__`.
+
+If you define an `async def __ainit__` method on a `@component` class, `pico-ioc` will automatically call and await it immediately after `__init__` is finished.
+
+```python
+import asyncio
+from pico_ioc import component, init
+
+@component
+class AsyncService:
+    def __init__(self):
+        # __init__ remains synchronous
+        self.connected = False
+        print("Service __init__ (sync)")
+
+    async def __ainit__(self):
+        # This is where you put your async setup code
+        print("Service __ainit__ (async) starting...")
+        await asyncio.sleep(0.01)  # Mock I/O
+        self.connected = True
+        print("Service __ainit__ finished.")
+
+# --- In your main async function ---
+async def main():
+    container = init(modules=[__name__])
+    
+    # .aget() will call __init__() and then await __ainit__()
+    service = await container.aget(AsyncService)
+    
+    assert service.connected is True
+
+# Output:
+# Service __init__ (sync)
+# Service __ainit__ (async) starting...
+# Service __ainit__ finished.
+```
+
+`__ainit__` can also have its own dependencies injected, just like `@configure`:
+
+```python
+from pico_ioc import component, init
+
+class AsyncDatabase:
+    async def ping(self): ...
+
+@component
+class DependsOnDB:
+    def __init__(self):
+        self.connected = False
+
+    async def __ainit__(self, db: AsyncDatabase):
+        await db.ping()
+        self.connected = True
+
+async def main():
+    container = init(modules=[__name__])
+    service = await container.aget(DependsOnDB)
+    assert service.connected is True
+```
+
+-----
+
+## 3\. Asynchronous Lifecycle Hooks
+
+The `@configure` and `@cleanup` decorators also work with `async def` methods.
+
+  * `async def @configure`: Called and awaited after `__ainit__`.
+  * `async def @cleanup`: Called and awaited by `container.cleanup_all_async()`.
+
+This is essential for gracefully shutting down async resources.
+
+```python
+from pico_ioc import component, configure, cleanup, init
+
+@component
+class AsyncConnectionPool:
+    async def __ainit__(self):
+        self.pool = await self.create_pool()
+        print("Pool created")
+
+    @configure
+    async def warmup(self):
+        # Optional post-init async setup
+        print("Warming up pool...")
+        await self.pool.prepare()
+        print("Pool warm")
+
+    @cleanup
+    async def close_pool(self):
+        # Use async def with @cleanup
+        print("Closing pool (async)...")
+        await self.pool.close()
+        print("Pool closed.")
+        
+    async def create_pool(self):
+        # Mock implementation
+        class Pool:
+            async def prepare(self): ...
+            async def close(self): ...
+        return Pool()
+
+# --- In your main async function ---
+async def main():
+    container = init(modules=[__name__])
+    pool = await container.aget(AsyncConnectionPool)
+    
+    print("Application shutting down...")
+    
+    # You MUST call the async version of cleanup
+    await container.cleanup_all_async()
+
+# Output:
+# Pool created
+# Warming up pool...
+# Pool warm
+# Application shutting down...
+# Closing pool (async)...
+# Pool closed.
+```
+
+-----
+
+## Summary
+
+  * Always use `container.aget()` from within an `async` function.
+  * Use `async def @provides` in a factory for async creation logic.
+  * Use `async def __ainit__` on a `@component` for async initialization logic; it can receive injected dependencies.
+  * Use `async def @configure` for post-initialization setup.
+  * Use `async def @cleanup` and `container.cleanup_all_async()` to gracefully release async resources.
+
+-----
+
+## Next Steps
+
+Now that you understand how to build and resolve components asynchronously, let's look at a powerful pattern for separating your application's concerns.
+
+  * AOP & Interceptors: Learn how to intercept method calls for logging, tracing, or caching. See: ./aop-interceptors.md# Advanced: Async Resolution (`aget`, `__ainit__`)
+
+Modern Python applications are increasingly built on `asyncio`. `pico-ioc` is async-native, meaning it fully supports asynchronous operations throughout the component lifecycle, from creation to cleanup.
+
+This guide covers how to:
+
+  * Resolve components asynchronously using `container.aget()`.
+  * Define components that require `await` during their creation.
+  * Use asynchronous lifecycle hooks like `@cleanup` and `@configure`.
+
+-----
+
+## 1\. `container.aget()`: The Async `get()`
+
+If you are in an `async` function, you should always use `container.aget()` instead of `container.get()`.
+
+  * `container.get()`: Synchronous. Blocks the event loop if a component needs to be created.
+  * `container.aget()`: Asynchronous. Properly awaits the creation of any async components, ensuring the event loop is never blocked.
+
+<!-- end list -->
+
+```python
+from pico_ioc import component, init
+
+@component
+class MyAsyncService:
+    ...
+
+async def main():
+    container = init(modules=[__name__])
+    
+    # Use .aget() inside an async function
+    service = await container.aget(MyAsyncService)
+    
+    # This would be bad! It could block.
+    # service = container.get(MyAsyncService)
+```
+
+-----
+
+## 2\. Asynchronous Component Creation
+
+Your components often need to perform I/O during their initialization (e.g., connect to a database, call an API). `pico-ioc` supports this in two primary ways.
+
+### Method 1: Async Factory (`async def @provides`)
+
+The cleanest way to create an async component is with a factory. You can decorate an `async def` method with `@provides`. `pico-ioc` will automatically await it when it's resolved via `container.aget()`.
+
+```python
+import asyncio
+from pico_ioc import component, factory, provides, init
+
+# A mock async database client
+class AsyncDatabase:
+    def __init__(self):
+        self.connected = True
+        print("Database connected")
+
+    @staticmethod
+    async def connect(url: str):
+        print(f"Connecting to {url}...")
+        await asyncio.sleep(0.01)  # Mock I/O
+        return AsyncDatabase()
+
+@factory
+class DatabaseFactory:
+    
+    # Use 'async def' with @provides
+    @provides(AsyncDatabase)
+    async def build_db(self) -> AsyncDatabase:
+        db = await AsyncDatabase.connect("postgres://...")
+        return db
+
+@component
+class UserService:
+    def __init__(self, db: AsyncDatabase):
+        self.db = db
+
+# --- In your main async function ---
+async def main():
+    container = init(modules=[__name__])
+    
+    # .aget() will correctly await the build_db() factory
+    user_service = await container.aget(UserService)
+    
+    assert user_service.db.connected is True
+
+# Output:
+# Connecting to postgres://...
+# Database connected
+```
+
+### Method 2: Async Constructor (`__ainit__`)
+
+You cannot make `__init__` an `async def` method in Python.
+
+To solve this, `pico-ioc` supports a special method: `__ainit__`.
+
+If you define an `async def __ainit__` method on a `@component` class, `pico-ioc` will automatically call and await it immediately after `__init__` is finished.
+
+```python
+import asyncio
+from pico_ioc import component, init
+
+@component
+class AsyncService:
+    def __init__(self):
+        # __init__ remains synchronous
+        self.connected = False
+        print("Service __init__ (sync)")
+
+    async def __ainit__(self):
+        # This is where you put your async setup code
+        print("Service __ainit__ (async) starting...")
+        await asyncio.sleep(0.01)  # Mock I/O
+        self.connected = True
+        print("Service __ainit__ finished.")
+
+# --- In your main async function ---
+async def main():
+    container = init(modules=[__name__])
+    
+    # .aget() will call __init__() and then await __ainit__()
+    service = await container.aget(AsyncService)
+    
+    assert service.connected is True
+
+# Output:
+# Service __init__ (sync)
+# Service __ainit__ (async) starting...
+# Service __ainit__ finished.
+```
+
+`__ainit__` can also have its own dependencies injected, just like `@configure`:
+
+```python
+from pico_ioc import component, init
+
+class AsyncDatabase:
+    async def ping(self): ...
+
+@component
+class DependsOnDB:
+    def __init__(self):
+        self.connected = False
+
+    async def __ainit__(self, db: AsyncDatabase):
+        await db.ping()
+        self.connected = True
+
+async def main():
+    container = init(modules=[__name__])
+    service = await container.aget(DependsOnDB)
+    assert service.connected is True
+```
+
+-----
+
+## 3\. Asynchronous Lifecycle Hooks
+
+The `@configure` and `@cleanup` decorators also work with `async def` methods.
+
+  * `async def @configure`: Called and awaited after `__ainit__`.
+  * `async def @cleanup`: Called and awaited by `container.cleanup_all_async()`.
+
+This is essential for gracefully shutting down async resources.
+
+```python
+from pico_ioc import component, configure, cleanup, init
+
+@component
+class AsyncConnectionPool:
+    async def __ainit__(self):
+        self.pool = await self.create_pool()
+        print("Pool created")
+
+    @configure
+    async def warmup(self):
+        # Optional post-init async setup
+        print("Warming up pool...")
+        await self.pool.prepare()
+        print("Pool warm")
+
+    @cleanup
+    async def close_pool(self):
+        # Use async def with @cleanup
+        print("Closing pool (async)...")
+        await self.pool.close()
+        print("Pool closed.")
+        
+    async def create_pool(self):
+        # Mock implementation
+        class Pool:
+            async def prepare(self): ...
+            async def close(self): ...
+        return Pool()
+
+# --- In your main async function ---
+async def main():
+    container = init(modules=[__name__])
+    pool = await container.aget(AsyncConnectionPool)
+    
+    print("Application shutting down...")
+    
+    # You MUST call the async version of cleanup
+    await container.cleanup_all_async()
+
+# Output:
+# Pool created
+# Warming up pool...
+# Pool warm
+# Application shutting down...
+# Closing pool (async)...
+# Pool closed.
+```
+
+-----
+
+## Summary
+
+  * Always use `container.aget()` from within an `async` function.
+  * Use `async def @provides` in a factory for async creation logic.
+  * Use `async def __ainit__` on a `@component` for async initialization logic; it can receive injected dependencies.
+  * Use `async def @configure` for post-initialization setup.
+  * Use `async def @cleanup` and `container.cleanup_all_async()` to gracefully release async resources.
+
+-----
+
+## Next Steps
+
+Now that you understand how to build and resolve components asynchronously, let's look at a powerful pattern for separating your application's concerns.
+
+  * AOP & Interceptors: Learn how to intercept method calls for logging, tracing, or caching. See: ./aop-interceptors.md