pico-ioc 2.1.1__py3-none-any.whl → 2.1.3__py3-none-any.whl

pico_ioc/_version.py

@@ -1 +1 @@
-__version__ = '2.1.1'
+__version__ = '2.1.3'

pico_ioc/analysis.py

@@ -1,7 +1,14 @@
 import inspect
 from dataclasses import dataclass
-from typing import Any, Callable, List, Optional, Tuple, Union, get_args, get_origin, Annotated
+import collections
+import collections.abc
+from typing import (
+    Any, Callable, List, Optional, Tuple, Union, get_args, get_origin, Annotated,
+    Iterable, Set, Sequence, Collection, Deque, FrozenSet, MutableSequence, MutableSet,
+    Dict, Mapping
+)
 from .decorators import Qualifier
+from .constants import LOGGER
 
 KeyT = Union[str, type]
 
@@ -12,6 +19,8 @@ class DependencyRequest:
     is_list: bool = False
     qualifier: Optional[str] = None
     is_optional: bool = False
+    is_dict: bool = False
+    dict_key_type: Any = None
 
 def _extract_annotated(ann: Any) -> Tuple[Any, Optional[str]]:
     qualifier = None
@@ -39,11 +48,27 @@ def _check_optional(ann: Any) -> Tuple[Any, bool]:
 def analyze_callable_dependencies(callable_obj: Callable[..., Any]) -> Tuple[DependencyRequest, ...]:
     try:
         sig = inspect.signature(callable_obj)
-    except (ValueError, TypeError):
+    except (ValueError, TypeError) as e:
+        LOGGER.debug(f"Could not analyze dependencies for {callable_obj!r}: {e}")
         return ()
 
     plan: List[DependencyRequest] = []
     
+    SUPPORTED_COLLECTION_ORIGINS = (
+        list,
+        set,
+        tuple,
+        frozenset,
+        collections.deque,
+        collections.abc.Iterable,
+        collections.abc.Collection,
+        collections.abc.Sequence,
+        collections.abc.MutableSequence,
+        collections.abc.MutableSet
+    )
+    
+    SUPPORTED_DICT_ORIGINS = (dict, collections.abc.Mapping)
+    
     for name, param in sig.parameters.items():
         if name in ("self", "cls"):
             continue
@@ -56,19 +81,35 @@ def analyze_callable_dependencies(callable_obj: Callable[..., Any]) -> Tuple[Dep
         base_type, qualifier = _extract_annotated(base_type)
 
         is_list = False
+        is_dict = False
         elem_t = None
+        dict_key_t = None
         
         origin = get_origin(base_type)
-        if origin in (list, List):
+        
+        if origin in SUPPORTED_COLLECTION_ORIGINS:
             is_list = True
             elem_t = get_args(base_type)[0] if get_args(base_type) else Any
             elem_t, list_qualifier = _extract_annotated(elem_t)
             if qualifier is None:
                 qualifier = list_qualifier
+        elif origin in SUPPORTED_DICT_ORIGINS:
+            is_dict = True
+            args = get_args(base_type)
+            dict_key_t = args[0] if args else Any
+            elem_t = args[1] if len(args) > 1 else Any
+            elem_t, dict_qualifier = _extract_annotated(elem_t)
+            if qualifier is None:
+                qualifier = dict_qualifier
         
         final_key: KeyT
+        final_dict_key_type: Any = None
+        
         if is_list:
             final_key = elem_t if isinstance(elem_t, type) else Any
+        elif is_dict:
+            final_key = elem_t if isinstance(elem_t, type) else Any
+            final_dict_key_type = dict_key_t
         elif isinstance(base_type, type):
             final_key = base_type
         elif isinstance(base_type, str):
@@ -84,9 +125,10 @@ def analyze_callable_dependencies(callable_obj: Callable[..., Any]) -> Tuple[Dep
                 key=final_key,
                 is_list=is_list,
                 qualifier=qualifier,
-                is_optional=is_optional or (param.default is not inspect._empty)
+                is_optional=is_optional or (param.default is not inspect._empty),
+                is_dict=is_dict,
+                dict_key_type=final_dict_key_type
             )
         )
     
     return tuple(plan)
-    

pico_ioc/aop.py

@@ -1,5 +1,3 @@
-# src/pico_ioc/aop.py
-
 import inspect
 import pickle
 import threading
@@ -75,15 +73,18 @@ def health(fn):
     return fn
 
 class UnifiedComponentProxy:
-    __slots__ = ("_target", "_creator", "_container", "_cache", "_lock")
-    def __init__(self, *, container: Any, target: Any = None, object_creator: Callable[[], Any] | None = None):
+    __slots__ = ("_target", "_creator", "_container", "_cache", "_lock", "_component_key")
+    
+    def __init__(self, *, container: Any, target: Any = None, object_creator: Callable[[], Any] | None = None, component_key: Any = None):
         if container is None:
             raise ValueError("UnifiedComponentProxy requires a non-null container")
         if target is None and object_creator is None:
             raise ValueError("UnifiedComponentProxy requires either a target or an object_creator")
+        
         object.__setattr__(self, "_container", container)
         object.__setattr__(self, "_target", target)
         object.__setattr__(self, "_creator", object_creator)
+        object.__setattr__(self, "_component_key", component_key)
         object.__setattr__(self, "_cache", {})
         object.__setattr__(self, "_lock", threading.RLock())
 
@@ -98,6 +99,7 @@ class UnifiedComponentProxy:
     def __setstate__(self, state):
         object.__setattr__(self, "_container", None)
         object.__setattr__(self, "_creator", None)
+        object.__setattr__(self, "_component_key", None)
         object.__setattr__(self, "_cache", {})
         object.__setattr__(self, "_lock", threading.RLock())
         try:
@@ -110,14 +112,17 @@ class UnifiedComponentProxy:
         tgt = object.__getattribute__(self, "_target")
         if tgt is not None:
             return tgt
+            
         lock = object.__getattribute__(self, "_lock")
         with lock:
             tgt = object.__getattribute__(self, "_target")
             if tgt is not None:
                 return tgt
+                
             creator = object.__getattribute__(self, "_creator")
             if not callable(creator):
                 raise TypeError("UnifiedComponentProxy object_creator must be callable")
+            
             tgt = creator()
             if tgt is None:
                 raise RuntimeError("UnifiedComponentProxy object_creator returned None")
@@ -128,27 +133,51 @@ class UnifiedComponentProxy:
                 if inspect.isawaitable(res):
                     raise AsyncResolutionError(
                         f"Lazy component {type(tgt).__name__} requires async "
-                        "@configure but was resolved via sync get()"
+                        "@configure but was resolved via sync access (proxy __getattr__). "
+                        "Use 'await container.aget(Component)' to force initialization."
                     )
 
             object.__setattr__(self, "_target", tgt)
             return tgt
+
+    async def _async_init_if_needed(self) -> None:
+        if object.__getattribute__(self, "_target") is not None:
+            return
+
+        lock = object.__getattribute__(self, "_lock")
+        tgt = object.__getattribute__(self, "_target")
+        if tgt is not None:
+            return
+
+        creator = object.__getattribute__(self, "_creator")
+        container = object.__getattribute__(self, "_container")
+        
+        tgt = creator() 
+        
+        if container and hasattr(container, "_run_configure_methods"):
+            res = container._run_configure_methods(tgt)
+            if inspect.isawaitable(res):
+                await res
+        
+        with lock:
+            object.__setattr__(self, "_target", tgt)
         
     def _scope_signature(self) -> Tuple[Any, ...]:
         container = object.__getattribute__(self, "_container")
-        target = object.__getattribute__(self, "_target")
+        key = object.__getattribute__(self, "_component_key")
         loc = getattr(container, "_locator", None)
-        if not loc:
+        
+        if not loc or key is None:
             return ()
-        if target is not None:
-            t = type(target)
-            for k, md in loc._metadata.items():
-                typ = md.provided_type or md.concrete_class
-                if isinstance(typ, type) and t is typ:
-                    sc = md.scope
-                    if sc == "singleton":
-                        return ()
-                    return (container.scopes.get_id(sc),)
+            
+        if key in loc._metadata:
+            md = loc._metadata[key]
+            sc = md.scope
+            if sc == "singleton":
+                return ()
+            
+            return (container.scopes.get_id(sc),)
+            
         return ()
         
     def _build_wrapped(self, name: str, bound: Callable[..., Any], interceptors_cls: Tuple[type, ...]):
@@ -212,6 +241,7 @@ class UnifiedComponentProxy:
         lock = object.__getattribute__(self, "_lock")
         with lock:
             cache: Dict[str, Tuple[Tuple[Any, ...], Callable[..., Any], Tuple[type, ...]]] = object.__getattribute__(self, "_cache")
+            
             cur_sig = self._scope_signature()
             cached = cache.get(name)
             
@@ -224,7 +254,12 @@ class UnifiedComponentProxy:
             cache[name] = (sig, wrapped, cls_tuple)
             return wrapped
         
-    def __setattr__(self, name, value): setattr(self._get_real_object(), name, value)
+    def __setattr__(self, name, value):
+        if name in ("_target", "_creator", "_container", "_cache", "_lock", "_component_key"):
+            object.__setattr__(self, name, value)
+        else:
+            setattr(self._get_real_object(), name, value)
+
     def __delattr__(self, name): delattr(self._get_real_object(), name)
     def __str__(self): return str(self._get_real_object())
     def __repr__(self): return repr(self._get_real_object())

pico_ioc/config_runtime.py

@@ -305,8 +305,11 @@ class ObjectGraphBuilder:
         if t is int:
             if isinstance(node, int):
                 return node
-            if isinstance(node, str) and node.strip().isdigit() or (isinstance(node, str) and node.strip().startswith("-") and node.strip()[1:].isdigit()):
-                return int(node)
+            if isinstance(node, str):
+                try:
+                    return int(node.strip())
+                except ValueError:
+                    pass
             raise ConfigurationError(f"Expected int at {'.'.join(path)}")
         if t is float:
             if isinstance(node, (int, float)):

pico_ioc/container.py

@@ -1,9 +1,10 @@
-# src/pico_ioc/container.py
-
 import inspect
 import contextvars
 import functools
-from typing import Any, Dict, List, Optional, Tuple, overload, Union, Callable, Iterable, Set, get_args, get_origin, Annotated, Protocol, Mapping
+from typing import (
+    Any, Dict, List, Optional, Tuple, overload, Union, Callable, 
+    Iterable, Set, get_args, get_origin, Annotated, Protocol, Mapping, Type
+)
 from contextlib import contextmanager
 from .constants import LOGGER, PICO_META
 from .exceptions import ComponentCreationError, ProviderNotFoundError, AsyncResolutionError, ConfigurationError
@@ -204,7 +205,11 @@ class PicoContainer:
                 args = self._resolve_args(configure_deps)
                 res = m(**args)
                 if inspect.isawaitable(res):
-                    LOGGER.warning(f"Async configure method {m} called during sync get. Awaitable ignored.")
+                    raise AsyncResolutionError(
+                        f"Component {type(instance).__name__} returned an awaitable from synchronous "
+                        f"@configure method '{m.__name__}'. You must use 'await container.aget()' "
+                        "or make the method synchronous."
+                    )
             return instance
 
         async def runner():
@@ -251,10 +256,12 @@ class PicoContainer:
     async def aget(self, key: KeyT) -> Any:
         instance_or_awaitable, took_ms, was_cached = self._resolve_or_create_internal(key)
 
+        instance = instance_or_awaitable
         if was_cached:
-            return instance_or_awaitable
+            if isinstance(instance, UnifiedComponentProxy):
+                await instance._async_init_if_needed()
+            return instance
 
-        instance = instance_or_awaitable
         if inspect.isawaitable(instance_or_awaitable):
             instance = await instance_or_awaitable
 
@@ -268,6 +275,10 @@ class PicoContainer:
                 instance = instance_or_awaitable_configured
 
         final_instance = self._maybe_wrap_with_aspects(key, instance)
+        
+        if isinstance(final_instance, UnifiedComponentProxy):
+             await final_instance._async_init_if_needed()
+             
         cache = self._cache_for(key)
         cache.put(key, final_instance)
         self.context.resolve_count += 1
@@ -281,7 +292,7 @@ class PicoContainer:
         cls = type(instance)
         for _, fn in inspect.getmembers(cls, predicate=lambda m: inspect.isfunction(m) or inspect.ismethod(m) or inspect.iscoroutinefunction(m)):
             if getattr(fn, "_pico_interceptors_", None):
-                return UnifiedComponentProxy(container=self, target=instance)
+                return UnifiedComponentProxy(container=self, target=instance, component_key=key)
         return instance
 
     def _iterate_cleanup_targets(self) -> Iterable[Any]:
@@ -373,7 +384,7 @@ class PicoContainer:
         self.cleanup_all()
         PicoContainer._container_registry.pop(self.container_id, None)
 
-    def build_resolution_graph(self) -> None:
+    def build_resolution_graph(self):
         return _build_resolution_graph(self._locator)
         
     def export_graph(
@@ -423,7 +434,7 @@ class PicoContainer:
             pid = _node_id(parent)
             for child in deps:
                 cid = _node_id(child)
-                lines.append(f"  {pid} -> {cid};")
+                lines.append(f"  {pid} -> {child};")
 
         lines.append("}")
 
@@ -433,19 +444,61 @@ class PicoContainer:
             
     def _resolve_args(self, dependencies: Tuple[DependencyRequest, ...]) -> Dict[str, Any]:
         kwargs: Dict[str, Any] = {}
-        if not dependencies:
+        if not dependencies or self._locator is None:
             return kwargs
             
         for dep in dependencies:
             if dep.is_list:
                 keys: Tuple[KeyT, ...] = ()
-                if self._locator is not None and isinstance(dep.key, type):
+                if isinstance(dep.key, type):
                     keys = tuple(self._locator.collect_by_type(dep.key, dep.qualifier))
                 kwargs[dep.parameter_name] = [self.get(k) for k in keys]
                 continue
+            
+            if dep.is_dict:
+                value_type = dep.key
+                key_type = dep.dict_key_type
+                result_map: Dict[Any, Any] = {}
+                
+                keys_to_resolve: Tuple[KeyT, ...] = ()
+                if isinstance(value_type, type):
+                    keys_to_resolve = tuple(self._locator.collect_by_type(value_type, dep.qualifier))
+                
+                for comp_key in keys_to_resolve:
+                    instance = self.get(comp_key)
+                    md = self._locator._metadata.get(comp_key)
+                    if md is None:
+                        continue
+                    
+                    dict_key: Any = None
+                    if key_type is str:
+                        dict_key = md.pico_name
+                        if dict_key is None:
+                            if isinstance(comp_key, str):
+                                dict_key = comp_key
+                            else:
+                                dict_key = getattr(comp_key, "__name__", str(comp_key))
+                    elif key_type is type or key_type is Type:
+                        dict_key = md.concrete_class or md.provided_type
+                    elif key_type is Any:
+                        dict_key = md.pico_name
+                        if dict_key is None:
+                            if isinstance(comp_key, str):
+                                dict_key = comp_key
+                            else:
+                                dict_key = getattr(comp_key, "__name__", str(comp_key))
+                    
+                    if dict_key is not None:
+                        if (key_type is type or key_type is Type) and not isinstance(dict_key, type):
+                            continue
+                        
+                        result_map[dict_key] = instance
+                        
+                kwargs[dep.parameter_name] = result_map
+                continue
 
             primary_key = dep.key
-            if isinstance(primary_key, str) and self._locator is not None:
+            if isinstance(primary_key, str):
                 mapped = self._locator.find_key_by_name(primary_key)
                 primary_key = mapped if mapped is not None else primary_key
             

pico_ioc/event_bus.py

@@ -155,25 +155,28 @@ class EventBus:
                 raise EventBusClosedError()
             if self._queue is None:
                 raise EventBusError("Worker queue not initialized. Call start_worker().")
-            loop = self._worker_loop
-            if loop and loop.is_running():
-                try:
-                    current_loop = asyncio.get_running_loop()
-                    if current_loop is loop:
-                        try:
-                            self._queue.put_nowait(event)
-                            return
-                        except asyncio.QueueFull:
-                            raise EventBusQueueFullError()
-                except RuntimeError:
-                    pass
-                try:
-                    loop.call_soon_threadsafe(self._queue.put_nowait, event)
-                    return
-                except asyncio.QueueFull:
-                    raise EventBusQueueFullError()
-            else:
-                raise EventBusError("Worker queue not initialized or loop not running. Call start_worker().")
+            
+            queue_ref = self._queue
+            loop_ref = self._worker_loop
+
+        if loop_ref and loop_ref.is_running():
+            try:
+                current_loop = asyncio.get_running_loop()
+                if current_loop is loop_ref:
+                    try:
+                        queue_ref.put_nowait(event)
+                        return
+                    except asyncio.QueueFull:
+                        raise EventBusQueueFullError()
+            except RuntimeError:
+                pass
+            try:
+                loop_ref.call_soon_threadsafe(queue_ref.put_nowait, event)
+                return
+            except asyncio.QueueFull:
+                raise EventBusQueueFullError()
+        else:
+            raise EventBusError("Worker queue not initialized or loop not running. Call start_worker().")
 
     async def aclose(self) -> None:
         await self.stop_worker()

pico_ioc/locator.py

@@ -80,9 +80,13 @@ class ComponentLocator:
                 return isinstance(inst, proto)
         except Exception:
             pass
+        
         for name, val in proto.__dict__.items():
-            if name.startswith("_") or not callable(val):
+            if name.startswith("_") or not (callable(val) or name in getattr(proto, "__annotations__", {})):
                 continue
+            
+            if not hasattr(typ, name):
+                return False
         return True
         
     def collect_by_type(self, t: type, q: Optional[str]) -> List[KeyT]:
@@ -122,6 +126,10 @@ class ComponentLocator:
                 if isinstance(dep.key, type):
                     keys = self.collect_by_type(dep.key, dep.qualifier)
                     deps.extend(keys)
+            elif dep.is_dict:
+                if isinstance(dep.key, type):
+                    keys = self.collect_by_type(dep.key, dep.qualifier)
+                    deps.extend(keys)
             else:
                 deps.append(dep.key)
         return tuple(deps)

pico_ioc/registrar.py

@@ -61,8 +61,8 @@ class Registrar:
         for key, md in list(self._metadata.items()):
             if md.lazy:
                 original = self._factory.get(key, origin='lazy')
-                def lazy_proxy_provider(_orig=original, _p=pico):
-                    return UnifiedComponentProxy(container=_p, object_creator=_orig)
+                def lazy_proxy_provider(_orig=original, _p=pico, _k=key):
+                    return UnifiedComponentProxy(container=_p, object_creator=_orig, component_key=_k)
                 self._factory.bind(key, lazy_proxy_provider)
 
 

pico_ioc/scope.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/scope.py
 import contextvars
 import inspect
 from typing import Any, Dict, Optional, Tuple
@@ -95,9 +94,10 @@ class ScopeManager:
 class ScopedCaches:
     def __init__(self, max_scopes_per_type: int = 2048) -> None:
         self._singleton = ComponentContainer()
-        self._by_scope: Dict[str, OrderedDict[Any, ComponentContainer]] = {}
+        self._by_scope: Dict[str, Dict[Any, ComponentContainer]] = {}
         self._max = int(max_scopes_per_type)
         self._no_cache = _NoCacheContainer()
+        
     def _cleanup_object(self, obj: Any) -> None:
         try:
             from .constants import PICO_META
@@ -132,15 +132,19 @@ class ScopedCaches:
             return self._singleton
         if scope == "prototype":
             return self._no_cache
+        
         sid = scopes.get_id(scope)
-        bucket = self._by_scope.setdefault(scope, OrderedDict())
+        
+        if sid is None:
+            raise ScopeError(
+                f"Cannot resolve component in scope '{scope}': No active scope ID found. "
+                f"Are you trying to use a {scope}-scoped component outside of its context?"
+            )
+
+        bucket = self._by_scope.setdefault(scope, {})
         if sid in bucket:
-            c = bucket.pop(sid)
-            bucket[sid] = c
-            return c
-        if len(bucket) >= self._max:
-            _, old = bucket.popitem(last=False)
-            self._cleanup_container(old)
+            return bucket[sid]
+        
         c = ComponentContainer()
         bucket[sid] = c
         return c
@@ -159,8 +163,11 @@ class ScopedCaches:
         bucket = self._by_scope.get(scope)
         if not bucket:
             return
-        k = max(0, int(keep))
-        while len(bucket) > k:
-            _, old = bucket.popitem(last=False)
-            self._cleanup_container(old)
-
+        
+        # Manual cleanup if needed, though we rely on explicit cleanup now
+        if len(bucket) > keep:
+            # Simple eviction strategy if forced manually
+            keys_to_remove = list(bucket.keys())[:len(bucket)-keep]
+            for k in keys_to_remove:
+                container = bucket.pop(k)
+                self._cleanup_container(container)

{pico_ioc-2.1.1.dist-info → pico_ioc-2.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.1.1
+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
@@ -58,49 +58,53 @@ Dynamic: license-file
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pico-ioc?period=monthly&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=Monthly+downloads)](https://pepy.tech/projects/pico-ioc)
+[![Docs](https://img.shields.io/badge/Docs-pico--ioc-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-ioc/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/learn-pico-ioc/)
+
 
 **Pico-IoC** is a **lightweight, async-ready, decorator-driven IoC container** built for clarity, testability, and performance.
-It brings *Inversion of Control* and *dependency injection* to Python in a deterministic, modern, and framework-agnostic way.
+It brings Inversion of Control and dependency injection to Python in a deterministic, modern, and framework-agnostic way.
 
-> 🐍 Requires **Python 3.10+**
+> 🐍 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).
+- 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.
+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__`, ...) |
+| 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.
+- 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.
 
 ---
 
@@ -108,26 +112,24 @@ As Python systems evolve, wiring dependencies by hand becomes fragile and unmain
 
 ```bash
 pip install pico-ioc
-````
+```
 
-For optional features, you can install extras:
+Optional extras:
 
-  * **YAML Configuration:**
+- YAML configuration support (requires PyYAML)
 
-    ```bash
-    pip install pico-ioc[yaml]
-    ```
+  ```bash
+  pip install pico-ioc[yaml]
+  ```
 
-    (Requires `PyYAML`)
+-----
 
-  * **Dependency Graph Export (Rendering):**
+### ⚠️ Important Note for v2.1.3+
 
-    ```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
-    ```
+**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.
 
 -----
 
@@ -139,7 +141,7 @@ 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
+@configured(prefix="APP_", mapping="auto")  # Auto-detects flat mapping
 @dataclass
 class Config:
     db_url: str = "sqlite:///demo.db"
@@ -147,14 +149,14 @@ class Config:
 # 2. Define components
 @component
 class Repo:
-    def __init__(self, cfg: Config): # Inject 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): # Inject Repo
+    def __init__(self, repo: Repo):  # Inject Repo
         self.repo = repo
     def run(self):
         return self.repo.fetch()
@@ -164,11 +166,11 @@ 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
+    EnvSource(prefix="")  # Read APP_DB_URL from environment
 )
 
 # 4. Initialize container
-container = init(modules=[__name__], config=config_ctx) # Pass context via 'config'
+container = init(modules=[__name__], config=config_ctx)  # Pass context via 'config'
 
 # 5. Get and use the service
 svc = container.get(Service)
@@ -178,7 +180,7 @@ print(svc.run())
 del os.environ['APP_DB_URL']
 ```
 
-**Output:**
+Output:
 
 ```
 fetching from postgresql://user:pass@host/db
@@ -199,7 +201,7 @@ test_config_ctx = configuration()
 container = init(
     modules=[__name__],
     config=test_config_ctx,
-    overrides={Repo: FakeRepo()} # Replace Repo with FakeRepo
+    overrides={Repo: FakeRepo()}  # Replace Repo with FakeRepo
 )
 
 svc = container.get(Service)
@@ -208,10 +210,56 @@ assert svc.run() == "fake-data"
 
 -----
 
+## 🧰 Profiles
+
+Use profiles to enable/disable components or configuration branches conditionally.
+
+```python
+# Enable "test" profile when bootstrapping the container
+container = init(
+    modules=[__name__],
+    profiles=["test"]
+)
+```
+
+Profiles are typically referenced in decorators or configuration mappings to include/exclude components and bindings.
+
+-----
+
+## ⚡ Async Components
+
+Pico-IoC supports async lifecycle and resolution.
+
+```python
+import asyncio
+from pico_ioc import component, init
+
+@component
+class AsyncRepo:
+    async def __ainit__(self):
+        # e.g., open async connections
+        self.ready = True
+
+    async def fetch(self):
+        return "async-data"
+
+async def main():
+    container = init(modules=[__name__])
+    repo = await container.aget(AsyncRepo)   # Async resolution
+    print(await repo.fetch())
+
+asyncio.run(main())
+```
+
+- `__ainit__` runs after construction if defined.
+- Use `container.aget(Type)` to resolve components that require async initialization or whose providers are async.
+
+-----
+
 ## 🩺 Lifecycle & AOP
 
 ```python
-import time # For example
+import time
 from pico_ioc import component, init, intercepted_by, MethodInterceptor, MethodCtx
 
 # Define an interceptor component
@@ -232,7 +280,7 @@ class LogInterceptor(MethodInterceptor):
 
 @component
 class Demo:
-    @intercepted_by(LogInterceptor) # Apply the interceptor
+    @intercepted_by(LogInterceptor)  # Apply the interceptor
     def work(self):
         print("   Working...")
         time.sleep(0.01)
@@ -244,7 +292,7 @@ result = c.get(Demo).work()
 print(f"Result: {result}")
 ```
 
-**Output:**
+Output:
 
 ```
 → calling Demo.work
@@ -255,19 +303,41 @@ Result: ok
 
 -----
 
+## 👁️ Observability & Cleanup
+
+- Export a dependency graph in DOT format:
+
+  ```python
+  c = init(modules=[...])
+  dot = c.export_graph()  # Returns DOT graph as a string
+  with open("dependencies.dot", "w") as f:
+      f.write(dot)
+  ```
+
+- Health checks:
+  - Annotate health probes inside components with `@health` for container-level reporting.
+  - The container exposes health information that can be queried in observability tooling.
+
+- Container cleanup:
+  - For sync components: `container.close()`
+  - For async components/resources: `await container.aclose()`
+
+Use cleanup in application shutdown hooks to release resources deterministically.
+
+-----
+
 ## 📖 Documentation
 
 The full documentation is available within the `docs/` directory of the project repository. Start with `docs/README.md` for navigation.
 
-  * **Getting Started:** `docs/getting-started.md`
-  * **User Guide:** `docs/user-guide/README.md`
-  * **Advanced Features:** `docs/advanced-features/README.md`
-  * **Observability:** `docs/observability/README.md`
-  * **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`
+- 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`
 
 -----
 
@@ -282,11 +352,10 @@ tox
 
 ## 🧾 Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) — *Significant redesigns and features in v2.0+.*
+See [CHANGELOG.md](./CHANGELOG.md) — Significant redesigns and features in v2.0+.
 
 -----
 
 ## 📜 License
 
 MIT — [LICENSE](https://opensource.org/licenses/MIT)
-

pico_ioc-2.1.3.dist-info/RECORD

@@ -0,0 +1,25 @@
+pico_ioc/__init__.py,sha256=i25Obx7aH_Oy5b6yjjnCswDgni7InIjrGEcG6vLAw6I,2414
+pico_ioc/_version.py,sha256=hgD1miBO_f3fboq1GKyV4DdK_igCLGJFnZRD7l9oNRs,22
+pico_ioc/analysis.py,sha256=cxlg3F3bwRIb-kVIqHp1RLYj-sk-GuIgCChE-pf0a7c,4189
+pico_ioc/aop.py,sha256=VkmLzoztPbFjLIqBmXohcCNd4w6UC9ZrqYOE8DsMQ7I,14417
+pico_ioc/api.py,sha256=0pcRFHzhDcX8ijd67xAsVrTejwXuJKz7kTKRUrIuX2s,6161
+pico_ioc/component_scanner.py,sha256=S-9XNxrgyq_JFdc4Uqn2bEb-HxafSgIWylIurxyN_UA,7955
+pico_ioc/config_builder.py,sha256=7kcYIq1Yrb46Tic7uLeaCDvLA-Sa_p1PIoGF00mivso,2848
+pico_ioc/config_registrar.py,sha256=34iNQY1TUEPTXbb-QV1T-c5VKAn18hBcNt5MLhzDSfY,8456
+pico_ioc/config_runtime.py,sha256=qdPIbGMXOf6KWMM7cva6W-hhbhybEY0swZN01R1emCg,12756
+pico_ioc/constants.py,sha256=AhIt0ieDZ9Turxb_YbNzj11wUbBbzjKfWh1BDlSx2Nw,183
+pico_ioc/container.py,sha256=SEEJCUHIOUz4Dghdmac2rDrv65Zlm2wiBKZt4WbZoDc,21354
+pico_ioc/decorators.py,sha256=ru_YeqyJ3gbfb6M8WeJZlBxfcBBEuGDvxpHJGzU6FIs,6412
+pico_ioc/dependency_validator.py,sha256=BIR6pKntACiabF6CjNZ3m00RMnet9BPK1_9y1iCJ5KQ,4144
+pico_ioc/event_bus.py,sha256=NSfmFPX6Zm2OmMJz16gJFYMhh65iI0n9UlC9M8GmO0c,8428
+pico_ioc/exceptions.py,sha256=FBuajj5g29hAGODt2tAWuy2sG5mQojdSddaqFzim-aY,2383
+pico_ioc/factory.py,sha256=oJXx_BYJuvV8oxYzs5I3gx9WM6uLYZ8GCc43gukNanc,1671
+pico_ioc/locator.py,sha256=JD6psgdGGsBoCwov-G76BrmTfKUoJ22sdwa6wVdmQV8,5064
+pico_ioc/provider_selector.py,sha256=pU7NbI5vifvUlJEjlRJmvveQUZVD47T24QmiP0CHRw0,1213
+pico_ioc/registrar.py,sha256=O22FYrMXQ4TvBf25b0CB1wwu9tjL-5e00n9Ubd8suNs,8394
+pico_ioc/scope.py,sha256=JmFJPSb9uG2oRSZ7YreCozOgqDHfYsYLcyCpqVI4luU,6427
+pico_ioc-2.1.3.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-2.1.3.dist-info/METADATA,sha256=-PWHmvXzShw_t9D-_vbGBN24aG7afVchr3ZFyGR0TrQ,12910
+pico_ioc-2.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-2.1.3.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-2.1.3.dist-info/RECORD,,

pico_ioc-2.1.1.dist-info/RECORD

@@ -1,25 +0,0 @@
-pico_ioc/__init__.py,sha256=i25Obx7aH_Oy5b6yjjnCswDgni7InIjrGEcG6vLAw6I,2414
-pico_ioc/_version.py,sha256=Aht2295j8FswZ-nPYofCYr3fBZ6Uyf0thTfl5Oc2mWA,22
-pico_ioc/analysis.py,sha256=k49R-HcDyvpSNid8mxv7Fc6fPHnDu1C_b4HxrGLNF2g,2780
-pico_ioc/aop.py,sha256=XcyzsuKPrVPk1_Jad7Mn-qwoL1y0ZuVWwRZBA-CslJk,13301
-pico_ioc/api.py,sha256=0pcRFHzhDcX8ijd67xAsVrTejwXuJKz7kTKRUrIuX2s,6161
-pico_ioc/component_scanner.py,sha256=S-9XNxrgyq_JFdc4Uqn2bEb-HxafSgIWylIurxyN_UA,7955
-pico_ioc/config_builder.py,sha256=7kcYIq1Yrb46Tic7uLeaCDvLA-Sa_p1PIoGF00mivso,2848
-pico_ioc/config_registrar.py,sha256=34iNQY1TUEPTXbb-QV1T-c5VKAn18hBcNt5MLhzDSfY,8456
-pico_ioc/config_runtime.py,sha256=hiL1kCxhpjbfOdUaH71jMGNESDpWsaJkQXh7q1T71bg,12781
-pico_ioc/constants.py,sha256=AhIt0ieDZ9Turxb_YbNzj11wUbBbzjKfWh1BDlSx2Nw,183
-pico_ioc/container.py,sha256=gXgQT12ChpexbZALUfb0YYohlcRbUUeJ8-ltdR7xitc,18956
-pico_ioc/decorators.py,sha256=ru_YeqyJ3gbfb6M8WeJZlBxfcBBEuGDvxpHJGzU6FIs,6412
-pico_ioc/dependency_validator.py,sha256=BIR6pKntACiabF6CjNZ3m00RMnet9BPK1_9y1iCJ5KQ,4144
-pico_ioc/event_bus.py,sha256=nOL91JLYxap9kbb-HBGEhOVwtXN_bfI4q0mtSRZFlHk,8434
-pico_ioc/exceptions.py,sha256=FBuajj5g29hAGODt2tAWuy2sG5mQojdSddaqFzim-aY,2383
-pico_ioc/factory.py,sha256=oJXx_BYJuvV8oxYzs5I3gx9WM6uLYZ8GCc43gukNanc,1671
-pico_ioc/locator.py,sha256=4WN1qvXXW_LRInB2XJR8pTgIuJ8RyWBSpVo28HwtlL0,4737
-pico_ioc/provider_selector.py,sha256=pU7NbI5vifvUlJEjlRJmvveQUZVD47T24QmiP0CHRw0,1213
-pico_ioc/registrar.py,sha256=hIk48nXghTdA3WBljCbw2q8J_6F_hCk1ljSi4Pb8P3A,8368
-pico_ioc/scope.py,sha256=hOdTmjjfrRt8APXoS3lbTbSPxILi7flBXz_qpIkpoKw,6137
-pico_ioc-2.1.1.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
-pico_ioc-2.1.1.dist-info/METADATA,sha256=deaBUX6MOzClrMVDDhk5siAh2W0QrtQI-w4n2ZI-gGI,10673
-pico_ioc-2.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-2.1.1.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-2.1.1.dist-info/RECORD,,