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

pico_ioc/dependency_validator.py

@@ -0,0 +1,103 @@
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union, Set
+from .factory import ComponentFactory, ProviderMetadata
+from .locator import ComponentLocator
+from .exceptions import InvalidBindingError
+from .analysis import DependencyRequest
+
+KeyT = Union[str, type]
+
+def _fmt(k: KeyT) -> str:
+    return getattr(k, '__name__', str(k))
+
+def _skip_type(t: type) -> bool:
+    if t in (str, int, float, bool, bytes):
+        return True
+    if t is Any:
+        return True
+    if getattr(t, "_is_protocol", False):
+        return True
+    return False
+
+class DependencyValidator:
+    def __init__(self, metadata: Dict[KeyT, ProviderMetadata], factory: ComponentFactory, locator: ComponentLocator):
+        self._metadata = metadata
+        self._factory = factory
+        self._locator = locator
+
+    def _find_md_for_type(self, t: type) -> Optional[ProviderMetadata]:
+        cands: List[ProviderMetadata] = []
+        for md in self._metadata.values():
+            typ = md.provided_type or md.concrete_class
+            if not isinstance(typ, type):
+                continue
+            try:
+                if issubclass(typ, t):
+                    cands.append(md)
+            except TypeError:
+                 pass
+            except Exception:
+                continue
+        if not cands:
+            if getattr(t, "_is_protocol", False):
+                 for md in self._metadata.values():
+                    typ = md.provided_type or md.concrete_class
+                    if isinstance(typ, type) and ComponentLocator._implements_protocol(typ, t):
+                        cands.append(md)
+
+        if not cands:
+            return None
+        prim = [m for m in cands if m.primary]
+        return prim[0] if prim else cands[0]
+
+
+    def _find_md_for_name(self, name: str) -> Optional[KeyT]:
+         return self._locator.find_key_by_name(name)
+
+
+    def validate_bindings(self) -> None:
+        errors: List[str] = []
+
+        for k, md in self._metadata.items():
+            if md.infra == "configuration":
+                continue
+
+            if not md.dependencies and md.infra not in ("configured", "component") and not md.override:
+                 continue
+            if md.infra == "component" and md.concrete_class and md.concrete_class.__init__ is object.__init__:
+                 continue
+
+
+            loc_name = f"component {_fmt(k)}"
+            if md.factory_method:
+                loc_name = f"factory method {md.factory_method}"
+
+            for dep in md.dependencies:
+                if dep.is_optional:
+                    continue
+
+                if dep.is_list:
+                    if dep.qualifier:
+                        if not self._locator.collect_by_type(dep.key, dep.qualifier) and isinstance(dep.key, type) and not _skip_type(dep.key):
+                            errors.append(f"{_fmt(k)} ({loc_name}) expects List[{_fmt(dep.key)}] with qualifier '{dep.qualifier}' but no matching components exist")
+                    continue
+
+                dep_key = dep.key
+                if isinstance(dep_key, str):
+                    key_found_by_name = self._find_md_for_name(dep_key)
+                    directly_bound = dep_key in self._metadata or self._factory.has(dep_key)
+                    if not key_found_by_name and not directly_bound:
+                        errors.append(f"{_fmt(k)} ({loc_name}) depends on string key '{dep_key}' which is not bound")
+                    continue
+
+                if isinstance(dep_key, type) and not _skip_type(dep_key):
+                    dep_key_found = self._factory.has(dep_key) or dep_key in self._metadata
+                    if not dep_key_found:
+                        assignable_md = self._find_md_for_type(dep_key)
+                        if assignable_md is None:
+                            by_name_key = self._find_md_for_name(getattr(dep_key, "__name__", ""))
+                            if by_name_key is None:
+                                errors.append(f"{_fmt(k)} ({loc_name}) depends on {_fmt(dep_key)} which is not bound")
+                    continue
+
+        if errors:
+            raise InvalidBindingError(errors)

pico_ioc/event_bus.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/event_bus.py
 import asyncio
 import inspect
 import logging
@@ -151,29 +150,30 @@ class EventBus:
             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().")
+        with self._lock:
+            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()
@@ -220,4 +220,3 @@ class PicoEventBusProvider:
             loop.create_task(event_bus.aclose())
         else:
             asyncio.run(event_bus.aclose())
-

pico_ioc/exceptions.py

@@ -14,21 +14,6 @@ class ProviderNotFoundError(PicoError):
         self.key = key
         self.origin = origin
 
-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)
@@ -84,4 +69,3 @@ class EventBusHandlerError(EventBusError):
         self.event_name = event_name
         self.handler_name = handler_name
         self.cause = cause
-

pico_ioc/factory.py

@@ -2,6 +2,7 @@
 from dataclasses import dataclass
 from typing import Any, Callable, Dict, Optional, Set, Tuple, Union
 from .exceptions import ProviderNotFoundError
+from .analysis import DependencyRequest
 
 KeyT = Union[str, type]
 Provider = Callable[[], Any]
@@ -18,6 +19,7 @@ class ProviderMetadata:
     lazy: bool
     infra: Optional[str]
     pico_name: Optional[Any]
+    dependencies: Tuple[DependencyRequest, ...] = ()
     override: bool = False
     scope: str = "singleton"
 
@@ -45,4 +47,3 @@ class DeferredProvider:
         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

@@ -1,45 +1,62 @@
-from typing import Any, Dict, Iterable, List, Optional, Set, Tuple, Union
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple, Union, get_origin, Annotated, get_args
 from .factory import ProviderMetadata
+from .decorators import Qualifier
+import inspect
+from .analysis import DependencyRequest
 
 KeyT = Union[str, type]
 
+def _get_signature_static(fn):
+    return inspect.signature(fn)
+
 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:
@@ -49,5 +66,62 @@ class ComponentLocator:
         else:
             c = {k for k in base if isinstance(k, t)}
         return self._new(c)
+        
     def keys(self) -> List[KeyT]:
-        return list(self._ensure())
+        return list(self._ensure())
+        
+    @staticmethod
+    def _implements_protocol(typ: type, proto: type) -> bool:
+        if not getattr(proto, "_is_protocol", False):
+            return False
+        try:
+            if getattr(proto, "__runtime_protocol__", False) or getattr(proto, "__annotations__", None) is not None:
+                inst = object.__new__(typ)
+                return isinstance(inst, proto)
+        except Exception:
+            pass
+        for name, val in proto.__dict__.items():
+            if name.startswith("_") or not callable(val):
+                continue
+        return True
+        
+    def collect_by_type(self, t: type, q: Optional[str]) -> List[KeyT]:
+        keys = list(self._metadata.keys())
+        out: List[KeyT] = []
+        for k in keys:
+            md = self._metadata.get(k)
+            if md is None:
+                continue
+            typ = md.provided_type or md.concrete_class
+            if not isinstance(typ, type):
+                continue
+            
+            ok = False
+            try:
+                ok = issubclass(typ, t)
+            except Exception:
+                ok = ComponentLocator._implements_protocol(typ, t)
+                
+            if ok and (q is None or q in md.qualifiers):
+                out.append(k)
+        return out
+        
+    def find_key_by_name(self, name: str) -> Optional[KeyT]:
+        for k, md in self._metadata.items():
+            if md.pico_name == name:
+                return k
+            typ = md.provided_type or md.concrete_class
+            if isinstance(typ, type) and getattr(typ, "__name__", "") == name:
+                return k
+        return None
+
+    def dependency_keys_for_static(self, md: ProviderMetadata):
+        deps: List[KeyT] = []
+        for dep in md.dependencies:
+            if dep.is_list:
+                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/provider_selector.py

@@ -0,0 +1,35 @@
+from typing import Dict, List, Tuple, Union
+from .factory import Provider, ProviderMetadata
+from .config_registrar import ConfigurationManager
+
+KeyT = Union[str, type]
+
+class ProviderSelector:
+    def __init__(self, config_manager: ConfigurationManager):
+        self._config_manager = config_manager
+
+    def _rank_provider(self, item: Tuple[bool, Provider, ProviderMetadata]) -> Tuple[int, int, int]:
+        provider, md = item[1], item[2]
+        
+        is_present = 1 if self._config_manager.prefix_exists(md) else 0
+        
+        pref = str(md.pico_name or "")
+        pref_len = len(pref)
+        
+        is_primary = 1 if item[0] else 0
+        
+        return (is_present, pref_len, is_primary)
+
+    def select_providers(
+        self,
+        candidates: Dict[KeyT, List[Tuple[bool, Provider, ProviderMetadata]]],
+    ) -> Dict[KeyT, Tuple[Provider, ProviderMetadata]]:
+        
+        winners: Dict[KeyT, Tuple[Provider, ProviderMetadata]] = {}
+        
+        for key, lst in candidates.items():
+            lst_sorted = sorted(lst, key=self._rank_provider, reverse=True)
+            chosen = lst_sorted[0]
+            winners[key] = (chosen[1], chosen[2])
+            
+        return winners

pico_ioc/registrar.py

@@ -0,0 +1,188 @@
+import os
+import inspect
+import logging
+import functools
+from dataclasses import is_dataclass, fields, MISSING
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union, get_args, get_origin, Iterable
+from .constants import LOGGER, PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
+from .exceptions import ConfigurationError, InvalidBindingError
+from .factory import ComponentFactory, ProviderMetadata, DeferredProvider
+from .locator import ComponentLocator
+from .aop import UnifiedComponentProxy
+from .decorators import Qualifier, get_return_type
+from .config_builder import ContextConfig
+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 .analysis import analyze_callable_dependencies, DependencyRequest
+from .container import PicoContainer
+
+KeyT = Union[str, type]
+Provider = Callable[[], Any]
+
+def _can_be_selected_for(reg_md: Dict[KeyT, ProviderMetadata], selector: Any) -> bool:
+    if not isinstance(selector, type):
+        return False
+    for md in reg_md.values():
+        typ = md.provided_type or md.concrete_class
+        if isinstance(typ, type):
+            try:
+                if issubclass(typ, selector):
+                    return True
+            except Exception:
+                continue
+    return False
+
+class Registrar:
+    def __init__(self, factory: ComponentFactory, *, profiles: Tuple[str, ...] = (), environ: Optional[Dict[str, str]] = None, logger: Optional[logging.Logger] = None, config: Optional[ContextConfig] = None) -> None:
+        self._factory = factory
+        self._profiles = set(p.strip() for p in profiles if p)
+        self._environ = environ if environ is not None else os.environ
+        self._metadata: Dict[KeyT, ProviderMetadata] = {}
+        self._indexes: Dict[str, Dict[Any, List[KeyT]]] = {}
+        self._log = logger or LOGGER
+        self._config_manager = ConfigurationManager(config)
+        self._provider_selector = ProviderSelector(self._config_manager)
+        self._scanner = ComponentScanner(self._profiles, self._environ, self._config_manager)
+        self._deferred: List[DeferredProvider] = []
+        self._provides_functions: Dict[KeyT, Callable[..., Any]] = {}
+
+
+    def locator(self) -> ComponentLocator:
+        loc = ComponentLocator(dict(self._metadata), dict(self._indexes))
+        setattr(loc, "_provides_functions", dict(self._provides_functions))
+        return loc
+
+    def attach_runtime(self, pico, locator: ComponentLocator) -> None:
+        for deferred in self._deferred:
+            deferred.attach(pico, locator)
+        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)
+                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():
+            typ = md.provided_type or md.concrete_class
+            if not isinstance(typ, type):
+                continue
+            try:
+                if issubclass(typ, t):
+                    cands.append(md)
+            except Exception:
+                continue
+        if not cands:
+            return None
+        prim = [m for m in cands if m.primary]
+        return prim[0] if prim else cands[0]
+
+    def _find_narrower_scope_from_deps(self, deps: Tuple[DependencyRequest, ...]) -> Optional[str]:
+        if not deps:
+            return None
+
+        for dep_req in deps:
+            if dep_req.is_list:
+                continue
+
+            dep_md = self._metadata.get(dep_req.key)
+            if dep_md is None:
+                if isinstance(dep_req.key, type):
+                    dep_md = self._find_md_for_type(dep_req.key)
+
+            if dep_md and dep_md.scope != "singleton":
+                return dep_md.scope
+        return None
+
+    def _promote_scopes(self) -> None:
+        for k, md in list(self._metadata.items()):
+            if md.scope == "singleton":
+                ns = self._find_narrower_scope_from_deps(md.dependencies)
+                if ns and ns != "singleton":
+                    self._metadata[k] = ProviderMetadata(key=md.key, provided_type=md.provided_type, concrete_class=md.concrete_class, factory_class=md.factory_class, factory_method=md.factory_method, qualifiers=md.qualifiers, primary=md.primary, lazy=md.lazy, infra=md.infra, pico_name=md.pico_name, override=md.override, scope=ns, dependencies=md.dependencies)
+
+    def _rebuild_indexes(self) -> None:
+        self._indexes.clear()
+        def add(idx: str, val: Any, key: KeyT):
+            b = self._indexes.setdefault(idx, {}).setdefault(val, [])
+            if key not in b:
+                b.append(key)
+
+        for k, md in self._metadata.items():
+            for q in md.qualifiers:
+                add("qualifier", q, k)
+            if md.primary:
+                add("primary", True, k)
+            add("lazy", bool(md.lazy), k)
+            if md.infra is not None:
+                add("infra", md.infra, k)
+            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
+        self._provides_functions = provides_functions
+
+        winners = self._provider_selector.select_providers(candidates)
+        for key, (provider, md) in winners.items():
+            self._bind_if_absent(key, provider)
+            self._metadata[key] = md
+            
+        if PicoContainer not in self._metadata:
+            self._factory.bind(PicoContainer, lambda: pico_instance)
+            self._metadata[PicoContainer] = ProviderMetadata(
+                key=PicoContainer,
+                provided_type=PicoContainer,
+                concrete_class=PicoContainer,
+                factory_class=None,
+                factory_method=None,
+                qualifiers=set(),
+                primary=True,
+                lazy=False,
+                infra="component",
+                pico_name="PicoContainer",
+                override=True,
+                scope="singleton",
+                dependencies=()
+            )
+
+        self._promote_scopes()
+        self._rebuild_indexes()
+
+        for _, selector, default_cls in sorted(on_missing, key=lambda x: -x[0]):
+            key = selector
+            if key in self._metadata or self._factory.has(key) or _can_be_selected_for(self._metadata, selector):
+                continue
+
+            deps = analyze_callable_dependencies(default_cls.__init__)
+            provider = DeferredProvider(lambda pico, loc, c=default_cls, d=deps: pico.build_class(c, loc, d))
+            qset = set(str(q) for q in getattr(default_cls, PICO_META, {}).get("qualifier", ()))
+            sc = getattr(default_cls, PICO_META, {}).get("scope", "singleton")
+            md = ProviderMetadata(key=key, provided_type=key if isinstance(key, type) else None, concrete_class=default_cls, factory_class=None, factory_method=None, qualifiers=qset, primary=True, lazy=bool(getattr(default_cls, PICO_META, {}).get("lazy", False)), infra=getattr(default_cls, PICO_INFRA, None), pico_name=getattr(default_cls, PICO_NAME, None), override=True, scope=sc, dependencies=deps)
+
+            self._bind_if_absent(key, provider)
+            self._metadata[key] = md
+            if isinstance(provider, DeferredProvider):
+                self._deferred.append(provider)
+
+        self._rebuild_indexes()
+
+        final_locator = ComponentLocator(self._metadata, self._indexes)
+        validator = DependencyValidator(self._metadata, self._factory, final_locator)
+        validator.validate_bindings()

pico_ioc/scope.py

@@ -3,6 +3,7 @@ import contextvars
 import inspect
 from typing import Any, Dict, Optional, Tuple
 from collections import OrderedDict
+from .exceptions import ScopeError
 
 class ScopeProtocol:
     def get_id(self) -> Any | None: ...
@@ -42,16 +43,24 @@ class ScopeManager:
         self._scopes: Dict[str, ScopeProtocol] = {
             "request": ContextVarScope(contextvars.ContextVar("pico_request_id", default=None)),
             "session": ContextVarScope(contextvars.ContextVar("pico_session_id", default=None)),
+            "websocket": ContextVarScope(contextvars.ContextVar("pico_websocket_id", default=None)),
             "transaction": ContextVarScope(contextvars.ContextVar("pico_tx_id", default=None)),
         }
-    def register_scope(self, name: str, implementation: ScopeProtocol) -> None:
+
+    def register_scope(self, name: str) -> 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'")
+            raise ScopeError(f"Cannot register reserved scope: '{name}'")
+        if name in self._scopes:
+            return
+
+        var_name = f"pico_{name}_id"
+        context_var = contextvars.ContextVar(var_name, default=None)
+        implementation = ContextVarScope(context_var)
         self._scopes[name] = implementation
+        
+        
     def get_id(self, name: str) -> Any | None:
         if name in ("singleton", "prototype"):
             return None