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

pico_ioc/policy.py

@@ -1,51 +1,39 @@
-# pico_ioc/policy.py
+# src/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 typing import Any, Dict, List, Optional, Tuple
+
 from .utils import create_alias_provider
-from .decorators import (
-    CONDITIONAL_META,
-    PRIMARY_FLAG,
-    ON_MISSING_META,
-)
+from .decorators import CONDITIONAL_META, PRIMARY_FLAG, ON_MISSING_META
+from . import _state
+
 
-# ---------------- helpers ----------------
+# ------------------- 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.
-    """
+    """Try to resolve the 'real' target behind a provider closure (class, function or bound method)."""
     fn = provider
     try:
         cells = getattr(fn, "__closure__", None) or ()
-        first_func = None
-        first_cls = None
+        first_func, first_cls = None, None
         for cell in cells:
             cc = getattr(cell, "cell_contents", None)
             if inspect.ismethod(cc):
-                return cc                    # highest priority: bound method
+                return cc
             if first_func is None and inspect.isfunction(cc):
-                first_func = cc              # keep first function seen
+                first_func = cc
             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
+                first_cls = cc
+        return first_func or first_cls or fn
     except Exception:
-        pass
-    return fn
+        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.
-    """
+    """If obj is a bound method, return the unbound function on its owner class."""
     try:
         if inspect.ismethod(obj) and getattr(obj, "__self__", None) is not None:
             owner = obj.__self__.__class__
@@ -60,96 +48,66 @@ def _owner_func(obj):
 
 
 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
+    """Look for metadata on object, its underlying function, or owner class method."""
+    val = getattr(target, attr_name, None)
+    if val is not None:
+        return val
     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
-            
+    if base_func:
+        val = getattr(base_func, attr_name, None)
+        if val is not None:
+            return val
+    of = _owner_func(target)
+    if of:
+        val = getattr(of, attr_name, None)
+        if val is not None:
+            return val
     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>}.
-    """
+    """Normalize @on_missing metadata."""
     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)
+    return (meta.get("selector"), int(meta.get("priority", 0)))
+
 
 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.
-    """
+    """Check if target is active given profiles/env/predicate."""
     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)
+    profs = tuple(meta.get("profiles", ()))
+    req_env = tuple(meta.get("require_env", ()))
+    pred = meta.get("predicate")
 
-    # 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 profs and (not profiles or not any(p in profs for p in profiles)):
+        return False
+    if req_env and not all(os.getenv(k) not in (None, "") for k in req_env):
+        return False
     if callable(pred):
         try:
             if not bool(pred()):
                 return False
         except Exception:
             return False
-
-    # default: active
     return True
 
-# ---------------- public API ----------------
+
+# ------------------- public API -------------------
 
 def apply_policy(container, *, profiles: Optional[List[str]] = None) -> None:
+    """Run all policy stages on the given container."""
     profiles = list(profiles or [])
 
     _filter_inactive_factory_candidates(container, profiles=profiles)
@@ -159,174 +117,129 @@ def apply_policy(container, *, profiles: Optional[List[str]] = None) -> None:
 
 
 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).
-    """
+    """Bind defaults declared with @on_missing if no binding exists for selector."""
     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]
+    # class components
+    for prov_key, meta in list(container._providers.items()):  # type: ignore
         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))
+        if om:
+            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]
+    # factory provides
+    for prov_key, meta in list(container._providers.items()):  # type: ignore
         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))
+        if om:
+            _sel, 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():
+    # bind highest priority candidate
+    for base, cands in defaults.items():
         if container.has(base):
             continue
-        candidates.sort(key=lambda t: t[0], reverse=True)
-        chosen_key = candidates[0][1]
+        cands.sort(key=lambda t: t[0], reverse=True)
+        chosen_key = cands[0][1]
 
-        def _make_delegate(_chosen_key=chosen_key):
-            def _factory():
-                return container.get(_chosen_key)
-            return _factory
+        def _delegate(_k=chosen_key):
+            def _f():
+                return container.get(_k)
+            return _f
 
-        container.bind(base, _make_delegate(), lazy=True)
+        container.bind(base, _delegate(), lazy=True)
 
-# ---------------- stages ----------------
+
+# ------------------- 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.
-    """
+    """Remove factories inactive under profiles/env/predicate."""
     to_delete = []
-    for prov_key, meta in list(container._providers.items()):  # type: ignore[attr-defined]
+    for prov_key, meta in list(container._providers.items()):  # type: ignore
         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:
+        if not _conditional_active(target, profiles=profiles):
             to_delete.append(prov_key)
     for k in to_delete:
-        container._providers.pop(k, None)  # type: ignore[attr-defined]
+        container._providers.pop(k, None)  # type: ignore
 
 
 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]
+    """For multiple factory candidates of same base, keep one (prefer @primary)."""
+    groups: dict[Any, list[tuple[Any, dict]]] = defaultdict(list)
+    for k, m in list(container._providers.items()):  # type: ignore
         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))
+        base = getattr(prov, "_pico_alias_for", None)
+        if base is not None:
+            groups[base].append((k, m))
 
-    for base, entries in alias_groups.items():
+    for base, entries in 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)
+            keep, _ = entries[0]
+            if (not container.has(base)) or (base != keep):
+                factory = create_alias_provider(container, keep)
                 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)
+        prims = [(kk, mm) for (kk, mm) in entries if _has_flag(_target_from_provider(mm["factory"]), PRIMARY_FLAG)]
+        if prims:
+            keep, _ = prims[0]
+            if (not container.has(base)) or (base != keep):
+                factory = create_alias_provider(container, keep)
                 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
+            for kk, _mm in entries:
+                if kk != keep and kk != base:
+                    container._providers.pop(kk, None)  # type: ignore
 
 
 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]
+    """For active class components, create base->impl aliases (prefer @primary)."""
+    impls: List[Tuple[type, dict]] = []
+    for key, meta in list(container._providers.items()):  # type: ignore
         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)
+    base_to_impls: Dict[Any, List[Tuple[Any, dict]]] = defaultdict(list)
     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))
+            base_to_impls[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]]] = []
+        regular, fallbacks = [], []
+        for ik, im in impl_list:
+            tgt = _target_from_provider(im["factory"])
+            (fallbacks if _on_missing_meta(tgt) else regular).append((ik, im))
 
-        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]:
+        def pick(cands: List[Tuple[Any, dict]]) -> 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:
+            prims = [(ik, im) for ik, im in cands if _has_flag(_target_from_provider(im["factory"]), PRIMARY_FLAG)]
+            return prims[0][0] if prims else cands[0][0]
+
+        chosen = pick(regular) or pick(fallbacks)
+        if not chosen:
             continue
 
-        factory = create_alias_provider(container, chosen_key)
+        factory = create_alias_provider(container, chosen)
         container.bind(base, factory, lazy=True)
 

pico_ioc/proxy.py

@@ -1,23 +1,25 @@
-# pico_ioc/proxy.py
-
+# src/pico_ioc/proxy.py
 from __future__ import annotations
+
+import inspect
 from functools import lru_cache
 from typing import Any, Callable, Sequence
-import inspect
 
 from .interceptors import Invocation, dispatch, MethodInterceptor
 
+
 class ComponentProxy:
+    """Proxy for lazy components. Creates the real object only when accessed."""
     def __init__(self, object_creator: Callable[[], Any]):
         object.__setattr__(self, "_object_creator", object_creator)
         object.__setattr__(self, "__real_object", None)
 
     def _get_real_object(self) -> Any:
-        real_obj = object.__getattribute__(self, "__real_object")
-        if real_obj is None:
-            real_obj = object.__getattribute__(self, "_object_creator")()
-            object.__setattr__(self, "__real_object", real_obj)
-        return real_obj
+        real = object.__getattribute__(self, "__real_object")
+        if real is None:
+            real = object.__getattribute__(self, "_object_creator")()
+            object.__setattr__(self, "__real_object", real)
+        return real
 
     @property
     def __class__(self):
@@ -29,6 +31,8 @@ class ComponentProxy:
     def __str__(self): return str(self._get_real_object())
     def __repr__(self): return repr(self._get_real_object())
     def __dir__(self): return dir(self._get_real_object())
+
+    # container-like behavior
     def __len__(self): return len(self._get_real_object())
     def __getitem__(self, key): return self._get_real_object()[key]
     def __setitem__(self, key, value): self._get_real_object()[key] = value
@@ -36,6 +40,8 @@ class ComponentProxy:
     def __iter__(self): return iter(self._get_real_object())
     def __reversed__(self): return reversed(self._get_real_object())
     def __contains__(self, item): return item in self._get_real_object()
+
+    # operators
     def __add__(self, other): return self._get_real_object() + other
     def __sub__(self, other): return self._get_real_object() - other
     def __mul__(self, other): return self._get_real_object() * other
@@ -50,6 +56,8 @@ class ComponentProxy:
     def __and__(self, other): return self._get_real_object() & other
     def __xor__(self, other): return self._get_real_object() ^ other
     def __or__(self, other): return self._get_real_object() | other
+
+    # reflected operators
     def __radd__(self, other): return other + self._get_real_object()
     def __rsub__(self, other): return other - self._get_real_object()
     def __rmul__(self, other): return other * self._get_real_object()
@@ -64,6 +72,8 @@ class ComponentProxy:
     def __rand__(self, other): return other & self._get_real_object()
     def __rxor__(self, other): return other ^ self._get_real_object()
     def __ror__(self, other): return other | self._get_real_object()
+
+    # misc
     def __neg__(self): return -self._get_real_object()
     def __pos__(self): return +self._get_real_object()
     def __abs__(self): return abs(self._get_real_object())
@@ -76,11 +86,15 @@ class ComponentProxy:
     def __ge__(self, other): return self._get_real_object() >= other
     def __hash__(self): return hash(self._get_real_object())
     def __bool__(self): return bool(self._get_real_object())
+
+    # callables & context
     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:
+    """Proxy that wraps an object and applies MethodInterceptors on method calls."""
     __slots__ = ("_target", "_interceptors")
 
     def __init__(self, target: object, interceptors: Sequence[MethodInterceptor]):
@@ -92,26 +106,24 @@ class IoCProxy:
         if not callable(attr):
             return attr
         if hasattr(attr, "__get__"):
-            fn = attr.__get__(self._target, type(self._target))
+            bound_fn = attr.__get__(self._target, type(self._target))
         else:
-            fn = attr
+            bound_fn = attr
 
         @lru_cache(maxsize=None)
-        def _wrap(bound_fn: Callable[..., Any]):
-            if inspect.iscoroutinefunction(bound_fn):
+        def _wrap(fn: Callable[..., Any]):
+            if inspect.iscoroutinefunction(fn):
                 async def aw(*args, **kwargs):
-                    inv = Invocation(self._target, name, bound_fn, args, kwargs)
-                    # dispatch returns a coroutine for async methods
+                    inv = Invocation(self._target, name, fn, args, kwargs)
                     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
+                    inv = Invocation(self._target, name, fn, args, kwargs)
                     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)
+        return _wrap(bound_fn)