pico-ioc 2.1.2__py3-none-any.whl → 2.2.0__py3-none-any.whl

pico_ioc/__init__.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/__init__.py
 from .constants import LOGGER_NAME, LOGGER, PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
 from .exceptions import (
     PicoError,
@@ -31,6 +30,7 @@ from .container import PicoContainer
 from .event_bus import EventBus, ExecPolicy, ErrorPolicy, Event, subscribe, AutoSubscriberMixin
 from .config_runtime import JsonTreeSource, YamlTreeSource, DictSource, Discriminator, Value
 from .analysis import DependencyRequest, analyze_callable_dependencies
+from .component_scanner import CustomScanner
 
 __all__ = [
     "LOGGER_NAME",
@@ -91,4 +91,5 @@ __all__ = [
     "Value",
     "DependencyRequest",
     "analyze_callable_dependencies",
+    "CustomScanner",
 ]

pico_ioc/_version.py

@@ -1 +1 @@
-__version__ = '2.1.2'
+__version__ = '2.2.0'

pico_ioc/analysis.py

@@ -8,6 +8,7 @@ from typing import (
     Dict, Mapping
 )
 from .decorators import Qualifier
+from .constants import LOGGER
 
 KeyT = Union[str, type]
 
@@ -47,20 +48,18 @@ 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 = (
-        # Runtime types
         list,
         set,
         tuple,
         frozenset,
         collections.deque,
-        
-        # Typing ABCs (from get_origin)
         collections.abc.Iterable,
         collections.abc.Collection,
         collections.abc.Sequence,

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/api.py

@@ -1,5 +1,3 @@
-# src/pico_ioc/api.py
-
 import importlib
 import pkgutil
 import logging
@@ -13,6 +11,8 @@ from .container import PicoContainer
 from .decorators import component, factory, provides, Qualifier, configure, cleanup, configured
 from .config_builder import ContextConfig, configuration
 from .registrar import Registrar
+from .aop import ContainerObserver
+from .component_scanner import CustomScanner
 
 KeyT = Union[str, type]
 Provider = Callable[[], Any]
@@ -63,7 +63,8 @@ def init(
     custom_scopes: Optional[Iterable[str]] = None,
     validate_only: bool = False,
     container_id: Optional[str] = None,
-    observers: Optional[List["ContainerObserver"]] = None,
+    observers: Optional[List[ContainerObserver]] = None,
+    custom_scanners: Optional[List[CustomScanner]] = None,
 ) -> PicoContainer:
     active = tuple(p.strip() for p in profiles if p)
     
@@ -82,6 +83,11 @@ def init(
             
     pico = PicoContainer(factory, caches, scopes, container_id=container_id, profiles=active, observers=observers or [])
     registrar = Registrar(factory, profiles=active, environ=environ, logger=logger, config=config)
+    
+    if custom_scanners:
+        for scanner in custom_scanners:
+            registrar.register_custom_scanner(scanner)
+
     for m in _iter_input_modules(modules):
         registrar.register_module(m)
         

pico_ioc/component_scanner.py

@@ -1,6 +1,6 @@
 import inspect
 import os
-from typing import Any, Callable, Dict, List, Optional, Tuple, Union, Set
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union, Set, Protocol
 from .constants import PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
 from .factory import ProviderMetadata, DeferredProvider
 from .decorators import get_return_type
@@ -10,6 +10,10 @@ from .analysis import analyze_callable_dependencies, DependencyRequest
 KeyT = Union[str, type]
 Provider = Callable[[], Any]
 
+class CustomScanner(Protocol):
+    def should_scan(self, obj: Any) -> bool: ...
+    def scan(self, obj: Any) -> Optional[Tuple[KeyT, Provider, ProviderMetadata]]: ...
+
 class ComponentScanner:
     def __init__(self, profiles: Set[str], environ: Dict[str, str], config_manager: ConfigurationManager):
         self._profiles = profiles
@@ -19,6 +23,10 @@ class ComponentScanner:
         self._on_missing: List[Tuple[int, KeyT, type]] = []
         self._deferred: List[DeferredProvider] = []
         self._provides_functions: Dict[KeyT, Callable[..., Any]] = {}
+        self._custom_scanners: List[CustomScanner] = []
+
+    def register_custom_scanner(self, scanner: CustomScanner) -> None:
+        self._custom_scanners.append(scanner)
 
     def get_scan_results(self) -> Tuple[Dict[KeyT, List[Tuple[bool, Provider, ProviderMetadata]]], List[Tuple[int, KeyT, type]], List[DeferredProvider], Dict[KeyT, Callable[..., Any]]]:
         return self._candidates, self._on_missing, self._deferred, self._provides_functions
@@ -86,7 +94,6 @@ class ComponentScanner:
         if has_instance_provides:
             factory_deps = analyze_callable_dependencies(cls.__init__)
 
-
         for name in dir(cls):
             try:
                 raw = inspect.getattr_static(cls, name)
@@ -140,27 +147,44 @@ class ComponentScanner:
         self._queue(k, provider, md)
         self._provides_functions[k] = fn
 
+    def _try_custom_scanners(self, obj: Any) -> bool:
+        for scanner in self._custom_scanners:
+            if scanner.should_scan(obj):
+                result = scanner.scan(obj)
+                if result:
+                    key, provider, md = result
+                    self._queue(key, provider, md)
+                    if isinstance(provider, DeferredProvider):
+                        self._deferred.append(provider)
+                    return True
+        return False
+
     def scan_module(self, module: Any) -> None:
         for _, obj in inspect.getmembers(module):
-            if inspect.isclass(obj):
-                meta = getattr(obj, PICO_META, {})
-                if "on_missing" in meta:
-                    sel = meta["on_missing"]["selector"]
-                    pr = int(meta["on_missing"].get("priority", 0))
-                    self._on_missing.append((pr, sel, obj))
-                    continue
-
-                infra = getattr(obj, PICO_INFRA, None)
-                if infra == "component":
-                    self._register_component_class(obj)
-                elif infra == "factory":
-                    self._register_factory_class(obj)
-                elif infra == "configured":
-                    enabled = self._enabled_by_condition(obj)
-                    reg_data = self._config_manager.register_configured_class(obj, enabled)
-                    if reg_data:
-                        self._queue(reg_data[0], reg_data[1], reg_data[2])
-
-        for _, fn in inspect.getmembers(module, predicate=inspect.isfunction):
-            if getattr(fn, PICO_INFRA, None) == "provides":
-                self._register_provides_function(fn)
+            if self._try_custom_scanners(obj):
+                continue
+
+            if inspect.isclass(obj) or getattr(obj, "_is_protocol", False):
+                if inspect.isclass(obj):
+                    meta = getattr(obj, PICO_META, {})
+                    
+                    if "on_missing" in meta:
+                        sel = meta["on_missing"]["selector"]
+                        pr = int(meta["on_missing"].get("priority", 0))
+                        self._on_missing.append((pr, sel, obj))
+                        continue
+
+                    infra = getattr(obj, PICO_INFRA, None)
+                    if infra == "component":
+                        self._register_component_class(obj)
+                    elif infra == "factory":
+                        self._register_factory_class(obj)
+                    elif infra == "configured":
+                        enabled = self._enabled_by_condition(obj)
+                        reg_data = self._config_manager.register_configured_class(obj, enabled)
+                        if reg_data:
+                            self._queue(reg_data[0], reg_data[1], reg_data[2])
+
+            elif inspect.isfunction(obj):
+                if getattr(obj, PICO_INFRA, None) == "provides":
+                    self._register_provides_function(obj)

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

@@ -205,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():
@@ -252,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
 
@@ -269,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
@@ -282,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]:
@@ -374,7 +384,11 @@ class PicoContainer:
         self.cleanup_all()
         PicoContainer._container_registry.pop(self.container_id, None)
 
-    def build_resolution_graph(self) -> None:
+    async def ashutdown(self) -> None:
+        await self.cleanup_all_async()
+        PicoContainer._container_registry.pop(self.container_id, None)
+        
+    def build_resolution_graph(self):
         return _build_resolution_graph(self._locator)
         
     def export_graph(
@@ -424,7 +438,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("}")
 

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/registrar.py

@@ -15,7 +15,7 @@ from .config_runtime import TreeSource
 from .config_registrar import ConfigurationManager
 from .provider_selector import ProviderSelector
 from .dependency_validator import DependencyValidator
-from .component_scanner import ComponentScanner
+from .component_scanner import ComponentScanner, CustomScanner
 from .analysis import analyze_callable_dependencies, DependencyRequest
 from .container import PicoContainer
 
@@ -49,6 +49,8 @@ class Registrar:
         self._deferred: List[DeferredProvider] = []
         self._provides_functions: Dict[KeyT, Callable[..., Any]] = {}
 
+    def register_custom_scanner(self, scanner: CustomScanner) -> None:
+        self._scanner.register_custom_scanner(scanner)
 
     def locator(self) -> ComponentLocator:
         loc = ComponentLocator(dict(self._metadata), dict(self._indexes))
@@ -61,20 +63,17 @@ 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)
 
-
     def _bind_if_absent(self, key: KeyT, provider: Provider) -> None:
         if not self._factory.has(key):
             self._factory.bind(key, provider)
 
-
     def register_module(self, module: Any) -> None:
         self._scanner.scan_module(module)
 
-
     def _find_md_for_type(self, t: type) -> Optional[ProviderMetadata]:
         cands: List[ProviderMetadata] = []
         for md in self._metadata.values():
@@ -133,7 +132,6 @@ class Registrar:
             if md.pico_name is not None:
                 add("pico_name", md.pico_name, k)
 
-
     def finalize(self, overrides: Optional[Dict[KeyT, Any]], *, pico_instance: PicoContainer) -> None:
         candidates, on_missing, deferred_providers, provides_functions = self._scanner.get_scan_results()
         self._deferred = deferred_providers

pico_ioc/scope.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/scope.py
 import contextvars
 import inspect
 from typing import Any, Dict, Optional, Tuple
@@ -93,11 +92,11 @@ class ScopeManager:
         return self.signature(self.names())
 
 class ScopedCaches:
-    def __init__(self, max_scopes_per_type: int = 2048) -> None:
+    def __init__(self) -> None:
         self._singleton = ComponentContainer()
-        self._by_scope: Dict[str, OrderedDict[Any, ComponentContainer]] = {}
-        self._max = int(max_scopes_per_type)
+        self._by_scope: Dict[str, Dict[Any, ComponentContainer]] = {}
         self._no_cache = _NoCacheContainer()
+        
     def _cleanup_object(self, obj: Any) -> None:
         try:
             from .constants import PICO_META
@@ -132,15 +131,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 +162,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.2.dist-info → pico_ioc-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.1.2
+Version: 2.2.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -28,7 +28,7 @@ License: MIT License
 Project-URL: Homepage, https://github.com/dperezcabrera/pico-ioc
 Project-URL: Repository, https://github.com/dperezcabrera/pico-ioc
 Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-ioc/issues
-Keywords: ioc,di,dependency injection,inversion of control,decorator
+Keywords: python,ioc,dependency-injection,di-container,inversion-of-control,ioc-container,zero-dependency,minimalistic,async,asyncio,modular,pluggable,ioc-framework,ioc-containers,inversion-of-control-container
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -62,7 +62,6 @@ Dynamic: license-file
 [![Docs](https://img.shields.io/badge/Docs-pico--ioc-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-ioc/)
 [![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/learn-pico-ioc/)
 
-
 **Pico-IoC** is a **lightweight, async-ready, decorator-driven IoC container** built for clarity, testability, and performance.
 It brings Inversion of Control and dependency injection to Python in a deterministic, modern, and framework-agnostic way.
 
@@ -97,14 +96,14 @@ Pico-IoC eliminates that friction by letting you declare how components relate
 
 ---
 
-## 🧩 Highlights (v2.0+)
+## 🧩 Highlights (v2.2+)
 
-- Unified Configuration: Use `@configured` to bind both flat (ENV-like) and tree (YAML/JSON) sources via the `configuration(...)` builder (ADR-0010).
-- Async-aware AOP system: Method interceptors via `@intercepted_by`.
-- Scoped resolution: singleton, prototype, request, session, transaction, and custom scopes.
-- `UnifiedComponentProxy`: Transparent `lazy=True` and AOP proxy supporting serialization.
-- Tree-based configuration runtime: Advanced mapping with reusable adapters and discriminators (`Annotated[Union[...], Discriminator(...)]`).
-- Observable container context: Built-in stats, health checks (`@health`), observer hooks (`ContainerObserver`), dependency graph export (`export_graph`), and async cleanup.
+- **Unified Configuration**: Use `@configured` to bind both flat (ENV-like) and tree (YAML/JSON) sources via the `configuration(...)` builder (ADR-0010).
+- **Extensible Scanning**: Use `CustomScanner` to hook into the discovery phase and register functions or custom decorators (ADR-0011).
+- **Async-aware AOP**: Method interceptors via `@intercepted_by`.
+- **Scoped resolution**: singleton, prototype, request, session, transaction, and custom scopes.
+- **Tree-based configuration**: Advanced mapping with reusable adapters (`Annotated[Union[...], Discriminator(...)]`).
+- **Observable context**: Built-in stats, health checks (`@health`), observer hooks (`ContainerObserver`), and dependency graph export.
 
 ---
 
@@ -116,11 +115,21 @@ pip install pico-ioc
 
 Optional extras:
 
-- YAML configuration support (requires PyYAML)
+  - YAML configuration support (requires PyYAML)
 
-  ```bash
-  pip install pico-ioc[yaml]
-  ```
+    ```bash
+    pip install pico-ioc[yaml]
+    ```
+
+-----
+
+### ⚠️ Important Note
+
+**Breaking Behavior in Scope Management (v2.1.3+):**
+**Scope LRU Eviction has been removed** to guarantee data integrity.
+
+  * **Frameworks (pico-fastapi):** Handled automatically.
+  * **Manual usage:** You **must** explicitly call `container._caches.cleanup_scope("scope_name", scope_id)` when a context ends to prevent memory leaks.
 
 -----
 
@@ -238,12 +247,16 @@ async def main():
     container = init(modules=[__name__])
     repo = await container.aget(AsyncRepo)   # Async resolution
     print(await repo.fetch())
+    
+    # Graceful async shutdown (calls @cleanup async methods)
+    await container.ashutdown()
 
 asyncio.run(main())
 ```
 
-- `__ainit__` runs after construction if defined.
-- Use `container.aget(Type)` to resolve components that require async initialization or whose providers are async.
+  - `__ainit__` runs after construction if defined.
+  - Use `container.aget(Type)` to resolve components that require async initialization.
+  - Use `await container.ashutdown()` to close resources cleanly.
 
 -----
 
@@ -283,35 +296,26 @@ result = c.get(Demo).work()
 print(f"Result: {result}")
 ```
 
-Output:
-
-```
-→ calling Demo.work
-   Working...
-← Demo.work done (10.xxms)
-Result: ok
-```
-
 -----
 
 ## 👁️ Observability & Cleanup
 
-- Export a dependency graph in DOT format:
+  - Export a dependency graph in DOT format:
 
-  ```python
-  c = init(modules=[...])
-  dot = c.export_graph()  # Returns DOT graph as a string
-  with open("dependencies.dot", "w") as f:
-      f.write(dot)
-  ```
+    ```python
+    c = init(modules=[...])
+    c.export_graph("dependencies.dot")  # Writes directly to file
+    ```
 
-- Health checks:
-  - Annotate health probes inside components with `@health` for container-level reporting.
-  - The container exposes health information that can be queried in observability tooling.
+  - Health checks:
 
-- Container cleanup:
-  - For sync components: `container.close()`
-  - For async components/resources: `await container.aclose()`
+      - Annotate health probes inside components with `@health` for container-level reporting.
+      - The container exposes health information that can be queried in observability tooling.
+
+  - Container cleanup:
+
+      - For sync apps: `container.shutdown()`
+      - For async apps: `await container.ashutdown()`
 
 Use cleanup in application shutdown hooks to release resources deterministically.
 
@@ -321,14 +325,14 @@ Use cleanup in application shutdown hooks to release resources deterministically
 
 The full documentation is available within the `docs/` directory of the project repository. Start with `docs/README.md` for navigation.
 
-- Getting Started: `docs/getting-started.md`
-- User Guide: `docs/user-guide/README.md`
-- Advanced Features: `docs/advanced-features/README.md`
-- Observability: `docs/observability/README.md`
-- Cookbook (Patterns): `docs/cookbook/README.md`
-- Architecture: `docs/architecture/README.md`
-- API Reference: `docs/api-reference/README.md`
-- ADR Index: `docs/adr/README.md`
+  - Getting Started: `docs/getting-started.md`
+  - User Guide: `docs/user-guide/README.md`
+  - Advanced Features: `docs/advanced-features/README.md`
+  - Observability: `docs/observability/README.md`
+  - Cookbook (Patterns): `docs/cookbook/README.md`
+  - Architecture: `docs/architecture/README.md`
+  - API Reference: `docs/api-reference/README.md`
+  - ADR Index: `docs/adr/README.md`
 
 -----
 
@@ -343,10 +347,11 @@ tox
 
 ## 🧾 Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) — Significant redesigns and features in v2.0+.
+See [CHANGELOG.md](https://www.google.com/search?q=./CHANGELOG.md) — Significant redesigns and features in v2.0+.
 
 -----
 
 ## 📜 License
 
 MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

pico_ioc-2.2.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+pico_ioc/__init__.py,sha256=MDneoBBB0JHD_o0_xzkOUeW4e3XjDJSaGMNTb5miBqw,2453
+pico_ioc/_version.py,sha256=Vyf6P6UCZKFeQtRzYujPmFfdlqSfnc01VEMWE3O0ZrA,22
+pico_ioc/analysis.py,sha256=cxlg3F3bwRIb-kVIqHp1RLYj-sk-GuIgCChE-pf0a7c,4189
+pico_ioc/aop.py,sha256=VkmLzoztPbFjLIqBmXohcCNd4w6UC9ZrqYOE8DsMQ7I,14417
+pico_ioc/api.py,sha256=KlZjI_4pJfD_1T32DgmOykii6L1V-5Xtcynd5d57YIA,6400
+pico_ioc/component_scanner.py,sha256=rRZSQbJ7SkssJ5SJBr_m2ih-lpFvVnDQpt-JrYH5Xsg,8999
+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=ipTpMwtCYuYfmJCjd7dfEtFFVR1PG0C1lZQp-wJ_UHw,21512
+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=0abgnJMJrEvEyqsvxBNTi6wl0iJHHjSaw75IuqGk56c,8531
+pico_ioc/scope.py,sha256=TFchqFE9ooDCtYV_9YaLdeJDMtmLdNbB63nbZp-AqI8,6349
+pico_ioc-2.2.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-2.2.0.dist-info/METADATA,sha256=HnQ9xsjsyPFA7zCIkzkkHLSngVut4bZQUjHHBsk9PXI,12901
+pico_ioc-2.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-2.2.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-2.2.0.dist-info/RECORD,,

pico_ioc-2.1.2.dist-info/RECORD

@@ -1,25 +0,0 @@
-pico_ioc/__init__.py,sha256=i25Obx7aH_Oy5b6yjjnCswDgni7InIjrGEcG6vLAw6I,2414
-pico_ioc/_version.py,sha256=m5qImnzcnIhayvILFVqEnXPYsN-vE0vxokygykKhRfw,22
-pico_ioc/analysis.py,sha256=Iy3fuXCVLV8xtT-qp-uxsb1QptHBLLrLYbTSfDkQ-OA,4145
-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=Ys1yLjiB3Qxxm_fvWCEYLSeaJ18LseWmXueAW8kHunk,20874
-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=JD6psgdGGsBoCwov-G76BrmTfKUoJ22sdwa6wVdmQV8,5064
-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.2.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
-pico_ioc-2.1.2.dist-info/METADATA,sha256=yerxK_c9JcZxnKqB-nWQL6bSovNLse9Qa67o2jD9R3I,12339
-pico_ioc-2.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-2.1.2.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-2.1.2.dist-info/RECORD,,