pico-ioc 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

pico_ioc/policy.py

@@ -0,0 +1,332 @@
+# pico_ioc/policy.py
+from __future__ import annotations
+
+import inspect
+import os
+from collections import defaultdict
+from typing import Any, Dict, Iterable, List, Tuple, Optional
+from .utils import create_alias_provider
+from .decorators import (
+    CONDITIONAL_META,
+    PRIMARY_FLAG,
+    ON_MISSING_META,
+)
+
+# ---------------- helpers ----------------
+
+def _target_from_provider(provider):
+    """
+    Best-effort: find the real target behind a provider closure.
+    Priority: bound method > plain function > class. Fallback to the provider itself.
+    """
+    fn = provider
+    try:
+        cells = getattr(fn, "__closure__", None) or ()
+        first_func = None
+        first_cls = None
+        for cell in cells:
+            cc = getattr(cell, "cell_contents", None)
+            if inspect.ismethod(cc):
+                return cc                    # highest priority: bound method
+            if first_func is None and inspect.isfunction(cc):
+                first_func = cc              # keep first function seen
+            elif first_cls is None and inspect.isclass(cc):
+                first_cls = cc               # keep first class seen
+        if first_func is not None:
+            return first_func
+        if first_cls is not None:
+            return first_cls
+    except Exception:
+        pass
+    return fn
+
+
+def _owner_func(obj):
+    """
+    If obj is a bound method, return the unbound function owned by the class (if resolvable).
+    This lets us read decorator flags placed on the original function.
+    """
+    try:
+        if inspect.ismethod(obj) and getattr(obj, "__self__", None) is not None:
+            owner = obj.__self__.__class__
+            name = getattr(obj, "__name__", None)
+            if name and hasattr(owner, name):
+                cand = getattr(owner, name)
+                if inspect.isfunction(cand):
+                    return cand
+    except Exception:
+        pass
+    return None
+
+
+def _find_attribute_on_target(target: Any, attr_name: str) -> Any:
+    """
+    Finds an attribute on a target object, searching the object itself,
+    its __func__ (for bound methods), or the owning class's function.
+    """
+    # 1. Check the object itself
+    value = getattr(target, attr_name, None)
+    if value is not None:
+        return value
+
+    # 2. Check the underlying function for bound methods
+    base_func = getattr(target, "__func__", None)
+    if base_func is not None:
+        value = getattr(base_func, attr_name, None)
+        if value is not None:
+            return value
+    
+    # 3. Check the function on the owner class
+    owner_func = _owner_func(target)
+    if owner_func is not None:
+        value = getattr(owner_func, attr_name, None)
+        if value is not None:
+            return value
+            
+    return None
+
+
+def _has_flag(obj, flag_name: str) -> bool:
+    """Reads a boolean decorator flag from the target."""
+    return bool(_find_attribute_on_target(obj, flag_name))
+
+
+def _get_meta(obj, meta_name: str) -> Any:
+    """Reads metadata (e.g., a dict) from the target."""
+    return _find_attribute_on_target(obj, meta_name)
+
+
+def _on_missing_meta(target):
+    """
+    Normalize @on_missing metadata.
+
+    IMPORTANT: The decorator stores {"selector": <T>, "priority": <int>}.
+    """
+    meta = _get_meta(target, ON_MISSING_META)
+    if not meta:
+        return None
+    selector = meta.get("selector")
+    prio = int(meta.get("priority", 0))
+    return (selector, prio)
+
+def _conditional_active(target, *, profiles: List[str]) -> bool:
+    """
+    Returns True if the target is active given profiles/env/predicate.
+    Activation logic (conjunctive across what's provided):
+      - If `profiles` present on target → at least one must match requested profiles.
+      - If `require_env` present → all listed env vars must be non-empty.
+      - If `predicate` present → must return True; exceptions → inactive (fail-closed).
+      - If none provided → active by default.
+    """
+    meta = _get_meta(target, CONDITIONAL_META)
+    if not meta:
+        return True
+
+    profs = tuple(meta.get("profiles", ())) or ()
+    req_env = tuple(meta.get("require_env", ())) or ()
+    pred = meta.get("predicate", None)
+
+    # 1) profiles (if declared)
+    if profs:
+        if not profiles or not any(p in profs for p in profiles):
+            return False
+
+    # 2) require_env (if declared)
+    if req_env:
+        if not all(os.getenv(k) not in (None, "") for k in req_env):
+            return False
+
+    # 3) predicate (if declared)
+    if callable(pred):
+        try:
+            if not bool(pred()):
+                return False
+        except Exception:
+            return False
+
+    # default: active
+    return True
+
+# ---------------- public API ----------------
+
+def apply_policy(container, *, profiles: Optional[List[str]] = None) -> None:
+    profiles = list(profiles or [])
+
+    _filter_inactive_factory_candidates(container, profiles=profiles)
+    _collapse_identical_keys_preferring_primary(container)
+    _create_active_component_base_aliases(container, profiles=profiles)
+    apply_defaults(container)
+
+
+def apply_defaults(container) -> None:
+    """
+    Bind default providers declared via @on_missing when no binding exists for the selector.
+
+    Supports:
+      - Class components decorated with @on_missing(Selector, priority=...)
+      - Factory @provides(...) where the provided method (or its owner) carries @on_missing
+        AND the provider got tagged with _pico_alias_for (the base type key).
+    """
+    defaults: dict[Any, list[tuple[int, Any]]] = {}
+
+    # (1) Class components with @on_missing
+    for prov_key, meta in list(container._providers.items()):  # type: ignore[attr-defined]
+        if not isinstance(prov_key, type):
+            continue
+        target = _target_from_provider(meta.get("factory"))
+        om = _on_missing_meta(target)
+        if not om:
+            continue
+        selector, prio = om
+        defaults.setdefault(selector, []).append((prio, prov_key))
+
+    # (2) Factory @provides(...) with @on_missing on the provided method/owner
+    for prov_key, meta in list(container._providers.items()):  # type: ignore[attr-defined]
+        prov = meta.get("factory")
+        base = getattr(prov, "_pico_alias_for", None)
+        if base is None:
+            continue
+        target = _target_from_provider(prov)
+        om = _on_missing_meta(target)
+        if not om:
+            continue
+        _selector_from_flag, prio = om
+        defaults.setdefault(base, []).append((prio, prov_key))
+
+    # Bind highest priority default for each selector if not already bound
+    for base, candidates in defaults.items():
+        if container.has(base):
+            continue
+        candidates.sort(key=lambda t: t[0], reverse=True)
+        chosen_key = candidates[0][1]
+
+        def _make_delegate(_chosen_key=chosen_key):
+            def _factory():
+                return container.get(_chosen_key)
+            return _factory
+
+        container.bind(base, _make_delegate(), lazy=True)
+
+# ---------------- stages ----------------
+
+def _filter_inactive_factory_candidates(container, *, profiles: List[str]) -> None:
+    """
+    Remove factory-provided candidates whose target is inactive under the given profiles/env/predicate.
+    This trims the candidate set early so later selection/aliasing runs on active options only.
+    """
+    to_delete = []
+    for prov_key, meta in list(container._providers.items()):  # type: ignore[attr-defined]
+        prov = meta.get("factory")
+        base = getattr(prov, "_pico_alias_for", None)
+        if base is None:
+            continue
+        target = _target_from_provider(prov)
+        active = _conditional_active(target, profiles=profiles)
+        if not active:
+            to_delete.append(prov_key)
+    for k in to_delete:
+        container._providers.pop(k, None)  # type: ignore[attr-defined]
+
+
+def _collapse_identical_keys_preferring_primary(container) -> None:
+    """
+    For factory-provided products of the same base type, collapse to a single alias:
+      - If any candidate is marked @primary -> pick the first primary.
+      - Else leave multiple to be decided by defaults or later alias logic.
+    """
+    alias_groups: dict[Any, list[tuple[Any, dict]]] = defaultdict(list)
+    for k, m in list(container._providers.items()):  # type: ignore[attr-defined]
+        prov = m.get("factory")
+        base_key = getattr(prov, "_pico_alias_for", None)
+        if base_key is not None:
+            alias_groups[base_key].append((k, m))
+
+    for base, entries in alias_groups.items():
+        if not entries:
+            continue
+
+        if len(entries) == 1:
+            keep_key, _ = entries[0]
+            if (not container.has(base)) or (base != keep_key):
+                factory = create_alias_provider(container, keep_key)
+                container.bind(base, factory, lazy=True)
+            continue
+
+        primaries: list[tuple[Any, dict]] = []
+        for (kk, mm) in entries:
+            tgt = _target_from_provider(mm.get("factory"))
+            if _has_flag(tgt, PRIMARY_FLAG):
+                primaries.append((kk, mm))
+
+        if primaries:
+            keep_key, _ = primaries[0]
+            if (not container.has(base)) or (base != keep_key):
+                factory = create_alias_provider(container, keep_key)
+                container.bind(base, factory, lazy=True)
+            for (kk, _mm) in entries:
+                if kk != keep_key and kk != base:
+                    container._providers.pop(kk, None)  # type: ignore[attr-defined]
+        else:
+            # multiple, no @primary -> leave for defaults
+            pass
+
+
+def _create_active_component_base_aliases(container, *, profiles: List[str]) -> None:
+    """
+    For class components (not factory-bound), create base->impl aliases among ACTIVE implementations.
+
+    Preference order:
+      1) Regular active implementations (non-@on_missing), prefer @primary; else first.
+      2) If none, fall back to @on_missing implementations, prefer @primary; else first.
+    """
+    base_to_impls: Dict[Any, List[Tuple[Any, Dict[str, Any]]]] = defaultdict(list)
+
+    # Collect active implementations
+    impls: List[Tuple[type, Dict[str, Any]]] = []
+    for key, meta in list(container._providers.items()):  # type: ignore[attr-defined]
+        if not isinstance(key, type):
+            continue
+        tgt = _target_from_provider(meta.get("factory"))
+        if _conditional_active(tgt, profiles=profiles):
+            impls.append((key, meta))
+
+    # Map each impl to all bases in its MRO (excluding itself and object)
+    for impl_key, impl_meta in impls:
+        for base in getattr(impl_key, "__mro__", ())[1:]:
+            if base is object:
+                break
+            base_to_impls.setdefault(base, []).append((impl_key, impl_meta))
+
+    # Choose per-base implementation with correct priority
+    for base, impl_list in base_to_impls.items():
+        if container.has(base) or not impl_list:
+            continue
+
+        regular: List[Tuple[Any, Dict[str, Any]]] = []
+        fallbacks: List[Tuple[Any, Dict[str, Any]]] = []
+
+        for (impl_key, impl_meta) in impl_list:
+            tgt = _target_from_provider(impl_meta.get("factory"))
+            if _on_missing_meta(tgt):
+                fallbacks.append((impl_key, impl_meta))
+            else:
+                regular.append((impl_key, impl_meta))
+
+        def pick(cands: List[Tuple[Any, Dict[str, Any]]]) -> Optional[Any]:
+            if not cands:
+                return None
+            primaries = []
+            for (ik, im) in cands:
+                tgt = _target_from_provider(im.get("factory"))
+                if _has_flag(tgt, PRIMARY_FLAG):
+                    primaries.append((ik, im))
+            chosen_key, _ = primaries[0] if primaries else cands[0]
+            return chosen_key
+
+        chosen_key = pick(regular) or pick(fallbacks)
+        if chosen_key is None:
+            continue
+
+        factory = create_alias_provider(container, chosen_key)
+        container.bind(base, factory, lazy=True)
+

pico_ioc/proxy.py

@@ -1,6 +1,11 @@
 # pico_ioc/proxy.py
 
-from typing import Any, Callable
+from __future__ import annotations
+from functools import lru_cache
+from typing import Any, Callable, Sequence
+import inspect
+
+from .interceptors import Invocation, dispatch, MethodInterceptor
 
 class ComponentProxy:
     def __init__(self, object_creator: Callable[[], Any]):
@@ -74,4 +79,39 @@ class ComponentProxy:
     def __call__(self, *args, **kwargs): return self._get_real_object()(*args, **kwargs)
     def __enter__(self): return self._get_real_object().__enter__()
     def __exit__(self, exc_type, exc_val, exc_tb): return self._get_real_object().__exit__(exc_type, exc_val, exc_tb)
+    
+class IoCProxy:
+    __slots__ = ("_target", "_interceptors")
+
+    def __init__(self, target: object, interceptors: Sequence[MethodInterceptor]):
+        self._target = target
+        self._interceptors = tuple(interceptors)
+
+    def __getattr__(self, name: str) -> Any:
+        attr = getattr(self._target, name)
+        if not callable(attr):
+            return attr
+        if hasattr(attr, "__get__"):
+            fn = attr.__get__(self._target, type(self._target))
+        else:
+            fn = attr
+
+        @lru_cache(maxsize=None)
+        def _wrap(bound_fn: Callable[..., Any]):
+            if inspect.iscoroutinefunction(bound_fn):
+                async def aw(*args, **kwargs):
+                    inv = Invocation(self._target, name, bound_fn, args, kwargs)
+                    # dispatch returns a coroutine for async methods
+                    return await dispatch(self._interceptors, inv)
+                return aw
+            else:
+                def sw(*args, **kwargs):
+                    inv = Invocation(self._target, name, bound_fn, args, kwargs)
+                    # dispatch returns a *value* for sync methods
+                    res = dispatch(self._interceptors, inv)
+                    if inspect.isawaitable(res):
+                        raise RuntimeError(f"Async interceptor on sync method: {name}")
+                    return res
+                return sw
+        return _wrap(fn)
 

pico_ioc/resolver.py

@@ -2,9 +2,12 @@
 
 from __future__ import annotations
 import inspect
-from typing import Any, Annotated, get_args, get_origin, get_type_hints
+from typing import Any, Annotated, get_args, get_origin, get_type_hints, Callable
+from contextvars import ContextVar
 
 
+_path: ContextVar[list[tuple[str, str]]] = ContextVar("pico_resolve_path", default=[])
+
 def _get_hints(obj, owner_cls=None) -> dict:
     """type hints with include_extras=True and correct globals/locals."""
     mod = inspect.getmodule(obj)
@@ -45,66 +48,82 @@ class Resolver:
         self.c = container
         self._prefer_name_first = bool(prefer_name_first)
 
-    def create_instance(self, cls):
-        sig = inspect.signature(cls.__init__)
-        hints = _get_hints(cls.__init__, owner_cls=cls)
-        kwargs = {}
-        for name, param in sig.parameters.items():
-            if name == "self":
-                continue
-            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
-                continue
-            ann = hints.get(name, param.annotation)
-            try:
-                value = self._resolve_param(name, ann)
-            except NameError:
-                if param.default is not inspect._empty:
-                    continue
-                raise
-            kwargs[name] = value
-        return cls(**kwargs)
 
-    def kwargs_for_callable(self, fn, *, owner_cls=None):
+    def _resolve_dependencies_for_callable(self, fn: Callable, owner_cls: Any = None) -> dict:
         sig = inspect.signature(fn)
         hints = _get_hints(fn, owner_cls=owner_cls)
         kwargs = {}
+    
+        path_owner = getattr(owner_cls, "__name__", getattr(fn, "__qualname__", "callable"))
+        if fn.__name__ == "__init__" and owner_cls:
+            path_owner = f"{path_owner}.__init__"
+
         for name, param in sig.parameters.items():
-            if name == "self":
-                continue
-            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD) or name == "self":
                 continue
+        
             ann = hints.get(name, param.annotation)
+            st = _path.get()
+            _path.set(st + [(path_owner, name)])
             try:
                 value = self._resolve_param(name, ann)
-            except NameError:
-                if param.default is not inspect._empty:
+                kwargs[name] = value
+            except NameError as e:
+                if param.default is not inspect.Parameter.empty:
+                    _path.set(st)
                     continue
-                raise
-            kwargs[name] = value
+
+                # If the error is already formatted with a chain, re-raise to preserve the full context.
+                if "(required by" in str(e):
+                    raise
+
+                # Otherwise, this is a fresh error; add the full chain for the first time.
+                chain = " -> ".join(f"{owner}.{param}" for owner, param in _path.get())
+                raise NameError(f"{e} (required by {chain})") from e
+            finally:
+                cur = _path.get()
+                if cur:
+                    _path.set(cur[:-1])
         return kwargs
 
+    def create_instance(self, cls: type) -> Any:
+        """Creates an instance of a class by resolving its __init__ dependencies."""
+        constructor_kwargs = self._resolve_dependencies_for_callable(cls.__init__, owner_cls=cls)
+        return cls(**constructor_kwargs)
+
+    def kwargs_for_callable(self, fn: Callable, *, owner_cls: Any = None) -> dict:
+        """Resolves all keyword arguments for any callable."""
+        return self._resolve_dependencies_for_callable(fn, owner_cls=owner_cls)
+
+
+    def _notify_resolve(self, key, ann, quals=()):
+        for ci in getattr(self.c, "_container_interceptors", ()):
+            try: ci.on_resolve(key, ann, tuple(quals) if quals else ())
+            except Exception: pass
+
     def _resolve_param(self, name: str, ann: Any):
-        # collections (list/tuple) with optional qualifiers via Annotated
+        # Colecciones (list/tuple)
         if _is_collection_hint(ann):
             base, quals, container_kind = _base_and_qualifiers_from_hint(ann)
+            self._notify_resolve(base, ann, quals)
             items = self.c._resolve_all_for_base(base, qualifiers=quals)
             return list(items) if container_kind is list else tuple(items)
 
-        # precedence: by name > by exact annotation > by MRO > by name again
+        # Precedencias
         if self._prefer_name_first and self.c.has(name):
+            self._notify_resolve(name, ann, ())
             return self.c.get(name)
-
         if ann is not inspect._empty and self.c.has(ann):
+            self._notify_resolve(ann, ann, ())
             return self.c.get(ann)
-
         if ann is not inspect._empty and isinstance(ann, type):
             for base in ann.__mro__[1:]:
                 if self.c.has(base):
+                    self._notify_resolve(base, ann, ())
                     return self.c.get(base)
-
         if self.c.has(name):
+            self._notify_resolve(name, ann, ())
             return self.c.get(name)
 
         missing = ann if ann is not inspect._empty else name
         raise NameError(f"No provider found for key {missing!r}")
-