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

pico_ioc/container.py

@@ -1,15 +1,18 @@
-# pico_ioc/container.py
+# src/pico_ioc/container.py
 from __future__ import annotations
+
 import inspect
 from typing import Any, Dict, get_origin, get_args, Annotated
-import typing as _t 
+import typing as _t
 
+from .proxy import IoCProxy
+from .interceptors import MethodInterceptor, ContainerInterceptor
 from .decorators import QUALIFIERS_KEY
-from . import _state  # re-entrancy guard
+from . import _state
 
 
 class Binder:
-    def __init__(self, container: "PicoContainer"):
+    def __init__(self, container: PicoContainer):
         self._c = container
 
     def bind(self, key: Any, provider, *, lazy: bool, tags: tuple[str, ...] = ()):
@@ -23,14 +26,38 @@ class Binder:
 
 
 class PicoContainer:
-    def __init__(self):
-        self._providers: Dict[Any, Dict[str, Any]] = {}
+    def __init__(self, providers: Dict[Any, Dict[str, Any]] | None = None):
+        self._providers = providers or {}
         self._singletons: Dict[Any, Any] = {}
+        self._method_interceptors: tuple[MethodInterceptor, ...] = ()
+        self._container_interceptors: tuple[ContainerInterceptor, ...] = ()
+        self._active_profiles: tuple[str, ...] = ()
+        self._seen_interceptor_types: set[type] = set()
+
+    # --- interceptors ---
+
+    def add_method_interceptor(self, it: MethodInterceptor) -> None:
+        t = type(it)
+        if t in self._seen_interceptor_types:
+            return
+        self._seen_interceptor_types.add(t)
+        self._method_interceptors = self._method_interceptors + (it,)
+
+    def add_container_interceptor(self, it: ContainerInterceptor) -> None:
+        t = type(it)
+        if t in self._seen_interceptor_types:
+            return
+        self._seen_interceptor_types.add(t)
+        self._container_interceptors = self._container_interceptors + (it,)
+
+    # --- binding ---
+
+    def binder(self) -> Binder:
+        return Binder(self)
 
     def bind(self, key: Any, provider, *, lazy: bool, tags: tuple[str, ...] = ()):
         self._singletons.pop(key, None)
         meta = {"factory": provider, "lazy": bool(lazy)}
-        # qualifiers already present:
         try:
             q = getattr(key, QUALIFIERS_KEY, ())
         except Exception:
@@ -39,11 +66,12 @@ class PicoContainer:
         meta["tags"] = tuple(tags) if tags else ()
         self._providers[key] = meta
 
+    # --- resolution ---
+
     def has(self, key: Any) -> bool:
         return key in self._providers
 
     def get(self, key: Any):
-        # block only when scanning and NOT currently resolving a dependency
         if _state._scanning.get() and not _state._resolving.get():
             raise RuntimeError("re-entrant container access during scan")
 
@@ -54,22 +82,49 @@ class PicoContainer:
         if key in self._singletons:
             return self._singletons[key]
 
-        # mark resolving around factory execution
+        for ci in self._container_interceptors:
+            try:
+                ci.on_before_create(key)
+            except Exception:
+                pass
+
         tok = _state._resolving.set(True)
         try:
-            instance = prov["factory"]()
+            try:
+                instance = prov["factory"]()
+            except BaseException as exc:
+                for ci in self._container_interceptors:
+                    try:
+                        ci.on_exception(key, exc)
+                    except Exception:
+                        pass
+                raise
         finally:
             _state._resolving.reset(tok)
 
-        # memoize always (both lazy and non-lazy after first get)
+        if self._method_interceptors and not isinstance(instance, IoCProxy):
+            instance = IoCProxy(instance, self._method_interceptors)
+
+        for ci in self._container_interceptors:
+            try:
+                maybe = ci.on_after_create(key, instance)
+                if maybe is not None:
+                    instance = maybe
+            except Exception:
+                pass
+
         self._singletons[key] = instance
         return instance
 
+    # --- lifecycle ---
+
     def eager_instantiate_all(self):
         for key, prov in list(self._providers.items()):
             if not prov["lazy"]:
                 self.get(key)
 
+    # --- helpers for multiples ---
+
     def get_all(self, base_type: Any):
         return tuple(self._resolve_all_for_base(base_type, qualifiers=()))
 
@@ -82,13 +137,8 @@ class PicoContainer:
             cls = provider_key if isinstance(provider_key, type) else None
             if cls is None:
                 continue
-
-            # Avoid self-inclusion loops: if the class itself requires a collection
-            # of `base_type` in its __init__, don't treat it as an implementation
-            # of `base_type` when building that collection.
             if _requires_collection_of_base(cls, base_type):
                 continue
-
             if _is_compatible(cls, base_type):
                 prov_qs = meta.get("qualifiers", ())
                 if all(q in prov_qs for q in qualifiers):
@@ -96,6 +146,11 @@ class PicoContainer:
                     matches.append(inst)
         return matches
 
+    def get_providers(self) -> Dict[Any, Dict]:
+        return self._providers.copy()
+
+
+# --- compatibility helpers ---
 
 def _is_protocol(t) -> bool:
     return getattr(t, "_is_protocol", False) is True
@@ -109,7 +164,6 @@ def _is_compatible(cls, base) -> bool:
         pass
 
     if _is_protocol(base):
-        # simple structural check: ensure methods/attrs declared on the Protocol exist on the class
         names = set(getattr(base, "__annotations__", {}).keys())
         names.update(n for n in getattr(base, "__dict__", {}).keys() if not n.startswith("_"))
         for n in names:
@@ -121,20 +175,15 @@ def _is_compatible(cls, base) -> bool:
 
     return False
 
+
 def _requires_collection_of_base(cls, base) -> bool:
-    """
-    Return True if `cls.__init__` has any parameter annotated as a collection
-    (list/tuple, including Annotated variants) of `base`. This prevents treating
-    `cls` as an implementation of `base` while building that collection,
-    avoiding recursion.
-    """
     try:
         sig = inspect.signature(cls.__init__)
     except Exception:
         return False
 
     try:
-        from .resolver import _get_hints  # type: ignore
+        from .resolver import _get_hints
         hints = _get_hints(cls.__init__, owner_cls=cls)
     except Exception:
         hints = {}
@@ -146,7 +195,6 @@ def _requires_collection_of_base(cls, base) -> bool:
         origin = get_origin(ann) or ann
         if origin in (list, tuple, _t.List, _t.Tuple):
             inner = (get_args(ann) or (object,))[0]
-            # Unwrap Annotated[T, ...] si aparece
             if get_origin(inner) is Annotated:
                 args = get_args(inner)
                 if args:
@@ -155,4 +203,3 @@ def _requires_collection_of_base(cls, base) -> bool:
                 return True
     return False
 
-

pico_ioc/decorators.py

@@ -1,7 +1,11 @@
-# pico_ioc/decorators.py
+# src/pico_ioc/decorators.py
 from __future__ import annotations
+
 import functools
-from typing import Any, Iterable
+from typing import Any, Iterable, Optional, Callable, Tuple, Literal
+
+
+# ---- marker attributes (read by scanner/policy) ----
 
 COMPONENT_FLAG = "_is_component"
 COMPONENT_KEY = "_component_key"
@@ -17,12 +21,23 @@ QUALIFIERS_KEY = "_pico_qualifiers"
 COMPONENT_TAGS = "_pico_tags"
 PROVIDES_TAGS = "_pico_tags"
 
+ON_MISSING_META = "_pico_on_missing"
+PRIMARY_FLAG = "_pico_primary"
+CONDITIONAL_META = "_pico_conditional"
+
+INTERCEPTOR_META = "__pico_interceptor__"
+
+
+# ---- core decorators ----
+
 def factory_component(cls):
+    """Mark a class as a factory component (its methods can @provides)."""
     setattr(cls, FACTORY_FLAG, True)
     return cls
 
 
 def component(cls=None, *, name: Any = None, lazy: bool = False, tags: Iterable[str] = ()):
+    """Mark a class as a component. Optional: custom key, lazy instantiation, tags."""
     def dec(c):
         setattr(c, COMPONENT_FLAG, True)
         setattr(c, COMPONENT_KEY, name if name is not None else c)
@@ -31,7 +46,9 @@ def component(cls=None, *, name: Any = None, lazy: bool = False, tags: Iterable[
         return c
     return dec(cls) if cls else dec
 
+
 def provides(key: Any, *, lazy: bool = False, tags: Iterable[str] = ()):
+    """Declare a factory method that provides a binding for `key`."""
     def dec(fn):
         @functools.wraps(fn)
         def w(*a, **k):
@@ -44,15 +61,20 @@ def provides(key: Any, *, lazy: bool = False, tags: Iterable[str] = ()):
 
 
 def plugin(cls):
+    """Mark a class as a Pico plugin (scanner lifecycle)."""
     setattr(cls, PLUGIN_FLAG, True)
     return cls
 
 
+# ---- qualifiers ----
+
 class Qualifier(str):
-    __slots__ = ()  # tiny memory win; immutable like str
+    """String qualifier type used with Annotated[T, 'q1', ...]."""
+    __slots__ = ()
 
 
 def qualifier(*qs: Qualifier):
+    """Attach one or more qualifiers to a component class key."""
     def dec(cls):
         current: Iterable[Qualifier] = getattr(cls, QUALIFIERS_KEY, ())
         seen = set(current)
@@ -66,14 +88,71 @@ def qualifier(*qs: Qualifier):
     return dec
 
 
+# ---- defaults / selection ----
+
+def on_missing(selector: object, *, priority: int = 0):
+    """Declare this target as a default for `selector` when no binding exists."""
+    def dec(obj):
+        setattr(obj, ON_MISSING_META, {"selector": selector, "priority": int(priority)})
+        return obj
+    return dec
+
+
+def primary(obj):
+    """Hint this candidate should be preferred among equals."""
+    setattr(obj, PRIMARY_FLAG, True)
+    return obj
+
+
+def conditional(
+    *,
+    profiles: Tuple[str, ...] = (),
+    require_env: Tuple[str, ...] = (),
+    predicate: Optional[Callable[[], bool]] = None,
+):
+    """Activate only when profiles/env/predicate conditions pass."""
+    def dec(obj):
+        setattr(obj, CONDITIONAL_META, {
+            "profiles": tuple(profiles),
+            "require_env": tuple(require_env),
+            "predicate": predicate,
+        })
+        return obj
+    return dec
+
+
+# ---- interceptors ----
+
+def interceptor(
+    _obj=None,
+    *,
+    kind: Literal["method", "container"] = "method",
+    order: int = 0,
+    profiles: Tuple[str, ...] = (),
+    require_env: Tuple[str, ...] = (),
+    predicate: Callable[[], bool] | None = None,
+):
+    """Declare an interceptor (method or container) with optional activation metadata."""
+    def dec(obj):
+        setattr(obj, INTERCEPTOR_META, {
+            "kind": kind,
+            "order": int(order),
+            "profiles": tuple(profiles),
+            "require_env": tuple(require_env),
+            "predicate": predicate,
+        })
+        return obj
+    return dec if _obj is None else dec(_obj)
+
+
 __all__ = [
-    # decorators
-    "component", "factory_component", "provides", "plugin", "qualifier",
-    # qualifier type
-    "Qualifier",
-    # metadata keys (exported for advanced use/testing)
+    "component", "factory_component", "provides", "plugin",
+    "Qualifier", "qualifier",
+    "on_missing", "primary", "conditional", "interceptor",
     "COMPONENT_FLAG", "COMPONENT_KEY", "COMPONENT_LAZY",
     "FACTORY_FLAG", "PROVIDES_KEY", "PROVIDES_LAZY",
-    "PLUGIN_FLAG", "QUALIFIERS_KEY", "COMPONENT_TAGS", "PROVIDES_TAGS"
+    "PLUGIN_FLAG", "QUALIFIERS_KEY", "COMPONENT_TAGS", "PROVIDES_TAGS",
+    "ON_MISSING_META", "PRIMARY_FLAG", "CONDITIONAL_META",
+    "INTERCEPTOR_META",
 ]
 

pico_ioc/interceptors.py

@@ -0,0 +1,56 @@
+# src/pico_ioc/interceptors.py
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Protocol, Sequence
+
+
+class Invocation:
+    __slots__ = ("target", "method_name", "call", "args", "kwargs", "is_async")
+
+    def __init__(self, target: object, method_name: str, call: Callable[..., Any],
+                 args: tuple, kwargs: dict):
+        self.target = target
+        self.method_name = method_name
+        self.call = call
+        self.args = args
+        self.kwargs = kwargs
+        self.is_async = inspect.iscoroutinefunction(call)
+
+
+class MethodInterceptor(Protocol):
+    def __call__(self, inv: Invocation, proceed: Callable[[], Any]) -> Any: ...
+
+
+async def _chain_async(interceptors: Sequence[MethodInterceptor], inv: Invocation, i: int = 0):
+    if i >= len(interceptors):
+        return await inv.call(*inv.args, **inv.kwargs)
+    cur = interceptors[i]
+
+    async def next_step():
+        return await _chain_async(interceptors, inv, i + 1)
+
+    res = cur(inv, next_step)
+    return await res if inspect.isawaitable(res) else res
+
+
+def _chain_sync(interceptors: Sequence[MethodInterceptor], inv: Invocation, i: int = 0):
+    if i >= len(interceptors):
+        return inv.call(*inv.args, **inv.kwargs)
+    cur = interceptors[i]
+    return cur(inv, lambda: _chain_sync(interceptors, inv, i + 1))
+
+
+def dispatch(interceptors: Sequence[MethodInterceptor], inv: Invocation):
+    """Dispatch invocation through a chain of interceptors."""
+    if inv.is_async:
+        return _chain_async(interceptors, inv, 0)  # coroutine
+    return _chain_sync(interceptors, inv, 0)       # value
+
+
+class ContainerInterceptor(Protocol):
+    def on_resolve(self, key: Any, annotation: Any, qualifiers: tuple[str, ...] | tuple()) -> None: ...
+    def on_before_create(self, key: Any) -> None: ...
+    def on_after_create(self, key: Any, instance: Any) -> Any: ...
+    def on_exception(self, key: Any, exc: BaseException) -> None: ...
+

pico_ioc/plugins.py

@@ -1,6 +1,7 @@
 # pico_ioc/plugins.py
-from typing import Protocol, Any
+from typing import Protocol, Any, Tuple
 from .container import Binder, PicoContainer
+import logging
 
 class PicoPlugin(Protocol):
     def before_scan(self, package: Any, binder: Binder) -> None: ...
@@ -10,3 +11,18 @@ class PicoPlugin(Protocol):
     def before_eager(self, container: PicoContainer, binder: Binder) -> None: ...
     def after_ready(self, container: PicoContainer, binder: Binder) -> None: ...
 
+def run_plugin_hook(
+    plugins: Tuple[PicoPlugin, ...],
+    hook_name: str,
+    *args,
+    **kwargs,
+) -> None:
+    """Run a lifecycle hook across all plugins, logging (but not raising) exceptions."""
+    for pl in plugins:
+        try:
+            fn = getattr(pl, hook_name, None)
+            if fn:
+                fn(*args, **kwargs)
+        except Exception:
+            logging.exception("Plugin %s failed", hook_name)
+

pico_ioc/policy.py

@@ -0,0 +1,245 @@
+# src/pico_ioc/policy.py
+from __future__ import annotations
+
+import inspect
+import os
+from collections import defaultdict
+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 . import _state
+
+
+# ------------------- helpers -------------------
+
+def _target_from_provider(provider):
+    """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, first_cls = None, None
+        for cell in cells:
+            cc = getattr(cell, "cell_contents", None)
+            if inspect.ismethod(cc):
+                return cc
+            if first_func is None and inspect.isfunction(cc):
+                first_func = cc
+            elif first_cls is None and inspect.isclass(cc):
+                first_cls = cc
+        return first_func or first_cls or fn
+    except Exception:
+        return fn
+
+
+def _owner_func(obj):
+    """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__
+            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:
+    """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:
+        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:
+    return bool(_find_attribute_on_target(obj, flag_name))
+
+
+def _get_meta(obj, meta_name: str) -> Any:
+    return _find_attribute_on_target(obj, meta_name)
+
+
+def _on_missing_meta(target):
+    """Normalize @on_missing metadata."""
+    meta = _get_meta(target, ON_MISSING_META)
+    if not meta:
+        return None
+    return (meta.get("selector"), int(meta.get("priority", 0)))
+
+
+def _conditional_active(target, *, profiles: List[str]) -> bool:
+    """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", ()))
+    req_env = tuple(meta.get("require_env", ()))
+    pred = meta.get("predicate")
+
+    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
+    return True
+
+
+# ------------------- 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)
+    _collapse_identical_keys_preferring_primary(container)
+    _create_active_component_base_aliases(container, profiles=profiles)
+    apply_defaults(container)
+
+
+def apply_defaults(container) -> None:
+    """Bind defaults declared with @on_missing if no binding exists for selector."""
+    defaults: dict[Any, list[tuple[int, Any]]] = {}
+
+    # 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 om:
+            selector, prio = om
+            defaults.setdefault(selector, []).append((prio, prov_key))
+
+    # 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 om:
+            _sel, prio = om
+            defaults.setdefault(base, []).append((prio, prov_key))
+
+    # bind highest priority candidate
+    for base, cands in defaults.items():
+        if container.has(base):
+            continue
+        cands.sort(key=lambda t: t[0], reverse=True)
+        chosen_key = cands[0][1]
+
+        def _delegate(_k=chosen_key):
+            def _f():
+                return container.get(_k)
+            return _f
+
+        container.bind(base, _delegate(), lazy=True)
+
+
+# ------------------- stages -------------------
+
+def _filter_inactive_factory_candidates(container, *, profiles: List[str]) -> None:
+    """Remove factories inactive under profiles/env/predicate."""
+    to_delete = []
+    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)
+        if not _conditional_active(target, profiles=profiles):
+            to_delete.append(prov_key)
+    for k in to_delete:
+        container._providers.pop(k, None)  # type: ignore
+
+
+def _collapse_identical_keys_preferring_primary(container) -> None:
+    """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 = getattr(prov, "_pico_alias_for", None)
+        if base is not None:
+            groups[base].append((k, m))
+
+    for base, entries in groups.items():
+        if not entries:
+            continue
+        if len(entries) == 1:
+            keep, _ = entries[0]
+            if (not container.has(base)) or (base != keep):
+                factory = create_alias_provider(container, keep)
+                container.bind(base, factory, lazy=True)
+            continue
+
+        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 and kk != base:
+                    container._providers.pop(kk, None)  # type: ignore
+
+
+def _create_active_component_base_aliases(container, *, profiles: List[str]) -> None:
+    """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))
+
+    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[base].append((impl_key, impl_meta))
+
+    for base, impl_list in base_to_impls.items():
+        if container.has(base) or not impl_list:
+            continue
+
+        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))
+
+        def pick(cands: List[Tuple[Any, dict]]) -> Optional[Any]:
+            if not cands:
+                return 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)
+        container.bind(base, factory, lazy=True)
+