pico-ioc 1.5.0__py3-none-any.whl → 2.0.1__py3-none-any.whl

pico_ioc/event_bus.py

@@ -0,0 +1,223 @@
+# src/pico_ioc/event_bus.py
+import asyncio
+import inspect
+import logging
+import threading
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any, Awaitable, Callable, Dict, Iterable, List, Optional, Tuple, Type
+from .api import factory, provides, configure, cleanup
+from .exceptions import EventBusClosedError, EventBusError, EventBusQueueFullError, EventBusHandlerError
+
+log = logging.getLogger(__name__)
+
+class ExecPolicy(Enum):
+    INLINE = auto()
+    THREADPOOL = auto()
+    TASK = auto()
+
+class ErrorPolicy(Enum):
+    LOG = auto()
+    RAISE = auto()
+
+class Event: ...
+
+@dataclass(order=True)
+class _Subscriber:
+    sort_index: int = field(init=False, repr=False, compare=True)
+    priority: int = field(compare=False)
+    callback: Callable[[Event], Any] | Callable[[Event], Awaitable[Any]] = field(compare=False)
+    policy: ExecPolicy = field(compare=False)
+    once: bool = field(compare=False)
+    def __post_init__(self):
+        self.sort_index = -int(self.priority)
+
+class EventBus:
+    def __init__(
+        self,
+        *,
+        default_exec_policy: ExecPolicy = ExecPolicy.INLINE,
+        error_policy: ErrorPolicy = ErrorPolicy.LOG,
+        max_queue_size: int = 0,
+    ):
+        self._subs: Dict[Type[Event], List[_Subscriber]] = {}
+        self._default_policy = default_exec_policy
+        self._error_policy = error_policy
+        self._queue: Optional[asyncio.Queue[Event]] = asyncio.Queue(max_queue_size) if max_queue_size >= 0 else None
+        self._worker_task: Optional[asyncio.Task] = None
+        self._worker_loop: Optional[asyncio.AbstractEventLoop] = None
+        self._closed = False
+        self._lock = threading.RLock()
+
+    def subscribe(
+        self,
+        event_type: Type[Event],
+        fn: Callable[[Event], Any] | Callable[[Event], Awaitable[Any]],
+        *,
+        priority: int = 0,
+        policy: Optional[ExecPolicy] = None,
+        once: bool = False,
+    ) -> None:
+        with self._lock:
+            if self._closed:
+                raise EventBusClosedError()
+            sub = _Subscriber(priority=priority, callback=fn, policy=policy or self._default_policy, once=once)
+            lst = self._subs.setdefault(event_type, [])
+            if any(s.callback is fn for s in lst):
+                return
+            lst.append(sub)
+            lst.sort()
+
+    def unsubscribe(self, event_type: Type[Event], fn: Callable[[Event], Any] | Callable[[Event], Awaitable[Any]]) -> None:
+        with self._lock:
+            lst = self._subs.get(event_type, [])
+            self._subs[event_type] = [s for s in lst if s.callback is not fn]
+
+    def publish_sync(self, event: Event) -> None:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            asyncio.run(self.publish(event))
+            return
+        if loop.is_running():
+            async def _bridge():
+                await self.publish(event)
+            loop.create_task(_bridge())
+        else:
+            asyncio.run(self.publish(event))
+
+    async def publish(self, event: Event) -> None:
+        if self._closed:
+            raise EventBusClosedError()
+        with self._lock:
+            subs = list(self._subs.get(type(event), []))
+        to_remove: List[_Subscriber] = []
+        pending: List[asyncio.Task] = []
+        for sub in subs:
+            try:
+                cb = sub.callback
+                if inspect.iscoroutinefunction(cb):
+                    if sub.policy is ExecPolicy.TASK:
+                        pending.append(asyncio.create_task(cb(event)))
+                    else:
+                        await cb(event)
+                else:
+                    if sub.policy is ExecPolicy.THREADPOOL:
+                        loop = asyncio.get_running_loop()
+                        await loop.run_in_executor(None, cb, event)
+                    else:
+                        cb(event)
+                if sub.once:
+                    to_remove.append(sub)
+            except Exception as ex:
+                self._handle_error(EventBusHandlerError(type(event).__name__, getattr(sub.callback, "__name__", "<callback>"), ex))
+        if pending:
+            try:
+                await asyncio.gather(*pending, return_exceptions=False)
+            except Exception as ex:
+                self._handle_error(EventBusError(f"Unhandled error awaiting event tasks: {ex}"))
+        if to_remove:
+            with self._lock:
+                lst = self._subs.get(type(event), [])
+                self._subs[type(event)] = [s for s in lst if s not in to_remove]
+
+    async def start_worker(self) -> None:
+        if self._closed:
+            raise EventBusClosedError()
+        if self._worker_task:
+            return
+        if self._queue is None:
+            self._queue = asyncio.Queue()
+        loop = asyncio.get_running_loop()
+        self._worker_loop = loop
+        async def _worker():
+            while True:
+                evt = await self._queue.get()
+                if evt is None:
+                    self._queue.task_done()
+                    break
+                try:
+                    await self.publish(evt)
+                finally:
+                    self._queue.task_done()
+        self._worker_task = asyncio.create_task(_worker())
+
+    async def stop_worker(self) -> None:
+        if self._worker_task and self._queue and self._worker_loop:
+            await self._queue.put(None)
+            await self._queue.join()
+            await self._worker_task
+            self._worker_task = None
+            self._worker_loop = None
+
+    def post(self, event: Event) -> None:
+        if self._closed:
+            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().")
+
+    async def aclose(self) -> None:
+        await self.stop_worker()
+        with self._lock:
+            self._closed = True
+            self._subs.clear()
+
+    def _handle_error(self, ex: EventBusError) -> None:
+        if self._error_policy is ErrorPolicy.RAISE:
+            raise ex
+        if self._error_policy is ErrorPolicy.LOG:
+            log.exception("%s", ex)
+
+def subscribe(event_type: Type[Event], *, priority: int = 0, policy: ExecPolicy = ExecPolicy.INLINE, once: bool = False):
+    def dec(fn: Callable[[Event], Any] | Callable[[Event], Awaitable[Any]]):
+        subs: Iterable[Tuple[Type[Event], int, ExecPolicy, bool]] = getattr(fn, "_pico_subscriptions_", ())
+        subs = list(subs)
+        subs.append((event_type, int(priority), policy, bool(once)))
+        setattr(fn, "_pico_subscriptions_", tuple(subs))
+        return fn
+    return dec
+
+class AutoSubscriberMixin:
+    @configure
+    def _pico_autosubscribe(self, event_bus: EventBus) -> None:
+        for _, attr in inspect.getmembers(self, predicate=callable):
+            subs: Iterable[Tuple[Type[Event], int, ExecPolicy, bool]] = getattr(attr, "_pico_subscriptions_", ())
+            for evt_t, pr, pol, once in subs:
+                event_bus.subscribe(evt_t, attr, priority=pr, policy=pol, once=once)
+
+@factory()
+class PicoEventBusProvider:
+    @provides(EventBus, primary=True)
+    def build(self) -> EventBus:
+        return EventBus()
+    @cleanup
+    def shutdown(self, event_bus: EventBus) -> None:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            asyncio.run(event_bus.aclose())
+            return
+        if loop.is_running():
+            loop.create_task(event_bus.aclose())
+        else:
+            asyncio.run(event_bus.aclose())
+

pico_ioc/exceptions.py

@@ -0,0 +1,72 @@
+from typing import Any, Iterable
+
+class PicoError(Exception):
+    pass
+
+class ProviderNotFoundError(PicoError):
+    def __init__(self, key: Any):
+        super().__init__(f"Provider not found for key: {getattr(key, '__name__', key)}")
+        self.key = key
+
+class CircularDependencyError(PicoError):
+    def __init__(self, chain: Iterable[Any], current: Any, details: str | None = None, hint: str | None = None):
+        chain_str = " -> ".join(getattr(k, "__name__", str(k)) for k in chain)
+        cur_str = getattr(current, "__name__", str(current))
+        base = f"Circular dependency detected: {chain_str} -> {cur_str}"
+        if details:
+            base += f"\n\n{details}"
+        if hint:
+            base += f"\n\nHint: {hint}"
+        super().__init__(base)
+        self.chain = tuple(chain)
+        self.current = current
+        self.details = details
+        self.hint = hint
+
+class ComponentCreationError(PicoError):
+    def __init__(self, key: Any, cause: Exception):
+        k = getattr(key, "__name__", key)
+        super().__init__(f"Failed to create component for key: {k}; cause: {cause.__class__.__name__}: {cause}")
+        self.key = key
+        self.cause = cause
+
+class ScopeError(PicoError):
+    def __init__(self, msg: str):
+        super().__init__(msg)
+
+class ConfigurationError(PicoError):
+    def __init__(self, msg: str):
+        super().__init__(msg)
+
+class SerializationError(PicoError):
+    def __init__(self, msg: str):
+        super().__init__(msg)
+
+class ValidationError(PicoError):
+    def __init__(self, msg: str):
+        super().__init__(msg)
+
+class InvalidBindingError(ValidationError):
+    def __init__(self, errors: list[str]):
+        super().__init__("Invalid bindings:\n" + "\n".join(f"- {e}" for e in errors))
+        self.errors = errors
+
+class EventBusError(PicoError):
+    def __init__(self, msg: str):
+        super().__init__(msg)
+
+class EventBusClosedError(EventBusError):
+    def __init__(self):
+        super().__init__("EventBus is closed")
+
+class EventBusQueueFullError(EventBusError):
+    def __init__(self):
+        super().__init__("Event queue is full")
+
+class EventBusHandlerError(EventBusError):
+    def __init__(self, event_name: str, handler_name: str, cause: Exception):
+        super().__init__(f"Handler {handler_name} failed for event {event_name}: {cause.__class__.__name__}: {cause}")
+        self.event_name = event_name
+        self.handler_name = handler_name
+        self.cause = cause
+

pico_ioc/factory.py

@@ -0,0 +1,48 @@
+# src/pico_ioc/factory.py
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, Set, Tuple, Union
+from .exceptions import ProviderNotFoundError
+
+KeyT = Union[str, type]
+Provider = Callable[[], Any]
+
+@dataclass(frozen=True)
+class ProviderMetadata:
+    key: KeyT
+    provided_type: Optional[type]
+    concrete_class: Optional[type]
+    factory_class: Optional[type]
+    factory_method: Optional[str]
+    qualifiers: Set[str]
+    primary: bool
+    lazy: bool
+    infra: Optional[str]
+    pico_name: Optional[Any]
+    override: bool = False
+    scope: str = "singleton"
+
+class ComponentFactory:
+    def __init__(self) -> None:
+        self._providers: Dict[KeyT, Provider] = {}
+    def bind(self, key: KeyT, provider: Provider) -> None:
+        self._providers[key] = provider
+    def has(self, key: KeyT) -> bool:
+        return key in self._providers
+    def get(self, key: KeyT) -> Provider:
+        if key not in self._providers:
+            raise ProviderNotFoundError(key)
+        return self._providers[key]
+
+class DeferredProvider:
+    def __init__(self, builder: Callable[[Any, Any], Any]) -> None:
+        self._builder = builder
+        self._pico: Any = None
+        self._locator: Any = None
+    def attach(self, pico, locator) -> None:
+        self._pico = pico
+        self._locator = locator
+    def __call__(self) -> Any:
+        if self._pico is None or self._locator is None:
+            raise RuntimeError("DeferredProvider must be attached before use")
+        return self._builder(self._pico, self._locator)
+

pico_ioc/locator.py

@@ -0,0 +1,53 @@
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple, Union
+from .factory import ProviderMetadata
+
+KeyT = Union[str, type]
+
+class ComponentLocator:
+    def __init__(self, metadata: Dict[KeyT, ProviderMetadata], indexes: Dict[str, Dict[Any, List[KeyT]]]) -> None:
+        self._metadata = metadata
+        self._indexes = indexes
+        self._candidates: Optional[Set[KeyT]] = None
+    def _ensure(self) -> Set[KeyT]:
+        return set(self._metadata.keys()) if self._candidates is None else set(self._candidates)
+    def _select_index(self, name: str, values: Iterable[Any]) -> Set[KeyT]:
+        out: Set[KeyT] = set()
+        idx = self._indexes.get(name, {})
+        for v in values:
+            out.update(idx.get(v, []))
+        return out
+    def _new(self, candidates: Set[KeyT]) -> "ComponentLocator":
+        nl = ComponentLocator(self._metadata, self._indexes)
+        nl._candidates = candidates
+        return nl
+    def with_index_any(self, name: str, *values: Any) -> "ComponentLocator":
+        base = self._ensure()
+        sel = self._select_index(name, values)
+        return self._new(base & sel)
+    def with_index_all(self, name: str, *values: Any) -> "ComponentLocator":
+        base = self._ensure()
+        cur = base
+        for v in values:
+            cur = cur & set(self._indexes.get(name, {}).get(v, []))
+        return self._new(cur)
+    def with_qualifier_any(self, *qs: Any) -> "ComponentLocator":
+        return self.with_index_any("qualifier", *qs)
+    def primary_only(self) -> "ComponentLocator":
+        return self.with_index_any("primary", True)
+    def lazy(self, is_lazy: bool = True) -> "ComponentLocator":
+        return self.with_index_any("lazy", True) if is_lazy else self.with_index_any("lazy", False)
+    def infra(self, *names: Any) -> "ComponentLocator":
+        return self.with_index_any("infra", *names)
+    def pico_name(self, *names: Any) -> "ComponentLocator":
+        return self.with_index_any("pico_name", *names)
+    def by_key_type(self, t: type) -> "ComponentLocator":
+        base = self._ensure()
+        if t is str:
+            c = {k for k in base if isinstance(k, str)}
+        elif t is type:
+            c = {k for k in base if isinstance(k, type)}
+        else:
+            c = {k for k in base if isinstance(k, t)}
+        return self._new(c)
+    def keys(self) -> List[KeyT]:
+        return list(self._ensure())

pico_ioc/scope.py

@@ -1,41 +1,157 @@
-from __future__ import annotations
-
-from typing import Any, Optional
-
-from .container import PicoContainer
-
-class ScopedContainer(PicoContainer):
-    def __init__(self, built_container: PicoContainer, base: Optional[PicoContainer], strict: bool):
-        super().__init__(providers=getattr(built_container, "_providers", {}).copy())
-        self._active_profiles = getattr(built_container, "_active_profiles", ())
-        base_method_its = getattr(base, "_method_interceptors", ()) if base else ()
-        base_container_its = getattr(base, "_container_interceptors", ()) if base else ()
-        self._method_interceptors = base_method_its
-        self._container_interceptors = base_container_its
-        self._seen_interceptor_types = {type(it) for it in base_container_its}
-        for it in getattr(built_container, "_method_interceptors", ()):
-            self.add_method_interceptor(it)
-        for it in getattr(built_container, "_container_interceptors", ()):
-            self.add_container_interceptor(it)
-        self._base = base
-        self._strict = strict
-        if base:
-            self._singletons.update(getattr(base, "_singletons", {}))
-
-    def __enter__(self): return self
-    def __exit__(self, exc_type, exc, tb): return False
-
-    def has(self, key: Any) -> bool:
-        if super().has(key): return True
-        if not self._strict and self._base is not None:
-            return self._base.has(key)
-        return False
-
-    def get(self, key: Any):
+# src/pico_ioc/scope.py
+import contextvars
+import inspect
+from typing import Any, Dict, Optional, Tuple
+from collections import OrderedDict
+
+class ScopeProtocol:
+    def get_id(self) -> Any | None: ...
+
+class ContextVarScope(ScopeProtocol):
+    def __init__(self, var: contextvars.ContextVar) -> None:
+        self._var = var
+    def get_id(self) -> Any | None:
+        return self._var.get()
+    def activate(self, scope_id: Any) -> contextvars.Token:
+        return self._var.set(scope_id)
+    def deactivate(self, token: contextvars.Token) -> None:
+        self._var.reset(token)
+
+class ComponentContainer:
+    def __init__(self) -> None:
+        self._instances: Dict[object, object] = {}
+    def get(self, key):
+        return self._instances.get(key)
+    def put(self, key, value):
+        self._instances[key] = value
+    def items(self):
+        return list(self._instances.items())
+
+class _NoCacheContainer(ComponentContainer):
+    def __init__(self) -> None:
+        pass
+    def get(self, key):
+        return None
+    def put(self, key, value):
+        return
+    def items(self):
+        return []
+
+class ScopeManager:
+    def __init__(self) -> None:
+        self._scopes: Dict[str, ScopeProtocol] = {
+            "request": ContextVarScope(contextvars.ContextVar("pico_request_id", default=None)),
+            "session": ContextVarScope(contextvars.ContextVar("pico_session_id", default=None)),
+            "transaction": ContextVarScope(contextvars.ContextVar("pico_tx_id", default=None)),
+        }
+    def register_scope(self, name: str, implementation: ScopeProtocol) -> None:
+        if not isinstance(name, str) or not name:
+            from .exceptions import ScopeError
+            raise ScopeError("Scope name must be a non-empty string")
+        if name in ("singleton", "prototype"):
+            from .exceptions import ScopeError
+            raise ScopeError("Cannot register or override reserved scopes: 'singleton' or 'prototype'")
+        self._scopes[name] = implementation
+    def get_id(self, name: str) -> Any | None:
+        if name in ("singleton", "prototype"):
+            return None
+        impl = self._scopes.get(name)
+        return impl.get_id() if impl else None
+    def activate(self, name: str, scope_id: Any) -> Optional[contextvars.Token]:
+        if name in ("singleton", "prototype"):
+            return None
+        impl = self._scopes.get(name)
+        if impl is None:
+            from .exceptions import ScopeError
+            raise ScopeError(f"Unknown scope: {name}")
+        if hasattr(impl, "activate"):
+            return getattr(impl, "activate")(scope_id)
+        return None
+    def deactivate(self, name: str, token: Optional[contextvars.Token]) -> None:
+        if name in ("singleton", "prototype"):
+            return
+        impl = self._scopes.get(name)
+        if impl is None:
+            from .exceptions import ScopeError
+            raise ScopeError(f"Unknown scope: {name}")
+        if token is not None and hasattr(impl, "deactivate"):
+            getattr(impl, "deactivate")(token)
+    def names(self) -> Tuple[str, ...]:
+        return tuple(n for n in self._scopes.keys() if n not in ("singleton", "prototype"))
+    def signature(self, names: Tuple[str, ...]) -> Tuple[Any, ...]:
+        return tuple(self.get_id(n) for n in names)
+    def signature_all(self) -> Tuple[Any, ...]:
+        return self.signature(self.names())
+
+class ScopedCaches:
+    def __init__(self, max_scopes_per_type: int = 2048) -> None:
+        self._singleton = ComponentContainer()
+        self._by_scope: Dict[str, OrderedDict[Any, ComponentContainer]] = {}
+        self._max = int(max_scopes_per_type)
+        self._no_cache = _NoCacheContainer()
+    def _cleanup_object(self, obj: Any) -> None:
         try:
-            return super().get(key)
-        except NameError as e:
-            if not self._strict and self._base is not None and self._base.has(key):
-                return self._base.get(key)
-            raise e
+            from .constants import PICO_META
+        except Exception:
+            PICO_META = "_pico_meta"
+        try:
+            for _, m in inspect.getmembers(obj, predicate=inspect.ismethod):
+                meta = getattr(m, PICO_META, {})
+                if meta.get("cleanup", False):
+                    try:
+                        m()
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+            
+    def cleanup_scope(self, scope_name: str, scope_id: Any) -> None:
+        bucket = self._by_scope.get(scope_name)
+        if bucket and scope_id in bucket:
+            container = bucket.pop(scope_id)
+            self._cleanup_container(container)
+
+    def _cleanup_container(self, container: "ComponentContainer") -> None:
+        try:
+            for _, obj in container.items():
+                self._cleanup_object(obj)
+        except Exception:
+            pass
+
+    def for_scope(self, scopes: ScopeManager, scope: str) -> ComponentContainer:
+        if scope == "singleton":
+            return self._singleton
+        if scope == "prototype":
+            return self._no_cache
+        sid = scopes.get_id(scope)
+        bucket = self._by_scope.setdefault(scope, OrderedDict())
+        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)
+        c = ComponentContainer()
+        bucket[sid] = c
+        return c
+
+    def all_items(self):
+        for item in self._singleton.items():
+            yield item
+        for b in self._by_scope.values():
+            for c in b.values():
+                for item in c.items():
+                    yield item
+
+    def shrink(self, scope: str, keep: int) -> None:
+        if scope in ("singleton", "prototype"):
+            return
+        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)