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

pico_ioc/builder.py

@@ -0,0 +1,242 @@
+# src/pico_ioc/builder.py
+from __future__ import annotations
+import inspect as _inspect
+import logging
+import os
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple
+from typing import get_origin, get_args, Annotated
+
+# Add missing imports for interceptor types
+from .interceptors import MethodInterceptor, ContainerInterceptor
+from .container import PicoContainer, _is_compatible
+from .policy import apply_policy, _conditional_active
+from .plugins import PicoPlugin, run_plugin_hook
+from .scanner import scan_and_configure
+from .resolver import Resolver, _get_hints
+from . import _state
+
+
+class PicoContainerBuilder:
+    def __init__(self):
+        self._scan_plan: List[Tuple[Any, Optional[Callable[[str], bool]], Tuple[PicoPlugin, ...]]] = []
+        self._overrides: Dict[Any, Any] = {}
+        self._profiles: Optional[List[str]] = None
+        self._plugins: Tuple[PicoPlugin, ...] = ()
+        self._include_tags: Optional[set[str]] = None
+        self._exclude_tags: Optional[set[str]] = None
+        self._roots: Iterable[type] = ()
+        self._providers: Dict[Any, Dict] = {}
+        self._interceptor_decls: List[Tuple[Any, dict]] = []
+
+    def with_plugins(self, plugins: Tuple[PicoPlugin, ...]) -> PicoContainerBuilder:
+        self._plugins = plugins
+        return self
+
+    def with_profiles(self, profiles: Optional[List[str]]) -> PicoContainerBuilder:
+        self._profiles = profiles
+        return self
+
+    def add_scan_package(self, package: Any, exclude: Optional[Callable[[str], bool]] = None) -> PicoContainerBuilder:
+        self._scan_plan.append((package, exclude, self._plugins))
+        return self
+
+    def with_overrides(self, overrides: Optional[Dict[Any, Any]]) -> PicoContainerBuilder:
+        self._overrides = overrides or {}
+        return self
+
+    def with_tag_filters(self, include: Optional[set[str]], exclude: Optional[set[str]]) -> PicoContainerBuilder:
+        self._include_tags = include
+        self._exclude_tags = exclude
+        return self
+
+    def with_roots(self, roots: Iterable[type]) -> PicoContainerBuilder:
+        self._roots = roots
+        return self
+
+    def build(self) -> PicoContainer:
+        requested_profiles = _resolve_profiles(self._profiles)
+        
+        # We now create a single container instance upfront and configure it.
+        container = PicoContainer(providers=self._providers)
+        container._active_profiles = tuple(requested_profiles)
+
+        for pkg, exclude, scan_plugins in self._scan_plan:
+            with _state.scanning_flag():
+                c, f, decls = scan_and_configure(pkg, container, exclude=exclude, plugins=scan_plugins)
+                logging.info("Scanned '%s' (components: %d, factories: %d)", getattr(pkg, "__name__", pkg), c, f)
+                self._interceptor_decls.extend(decls)
+
+        _activate_and_build_interceptors(
+            container=container,
+            interceptor_decls=self._interceptor_decls,
+            profiles=requested_profiles
+        )
+        
+        binder = container.binder()
+
+        if self._overrides:
+            _apply_overrides(container, self._overrides)
+
+        run_plugin_hook(self._plugins, "after_bind", container, binder)
+        run_plugin_hook(self._plugins, "before_eager", container, binder)
+        apply_policy(container, profiles=requested_profiles)
+        _filter_by_tags(container, self._include_tags, self._exclude_tags)
+        if self._roots:
+            _restrict_to_subgraph(container, self._roots, self._overrides)
+
+        run_plugin_hook(self._plugins, "after_ready", container, binder)
+        container.eager_instantiate_all()
+        logging.info("Container configured and ready.")
+        return container
+
+# ... (Helper functions like _resolve_profiles, _apply_overrides etc. remain here) ...
+# --- Start of moved helpers ---
+def _resolve_profiles(profiles: Optional[list[str]]) -> list[str]:
+    if profiles is not None:
+        return list(profiles)
+    env_val = os.getenv("PICO_PROFILE", "")
+    return [p.strip() for p in env_val.split(",") if p.strip()]
+
+def _as_provider(val):
+    if isinstance(val, tuple) and len(val) == 2 and callable(val[0]) and isinstance(val[1], bool):
+        return val[0], val[1]
+    if callable(val):
+        return val, False
+    return (lambda v=val: v), False
+
+def _apply_overrides(container: PicoContainer, overrides: Dict[Any, Any]) -> None:
+    for key, val in overrides.items():
+        provider, lazy = _as_provider(val)
+        container.bind(key, provider, lazy=lazy)
+
+def _filter_by_tags(container: PicoContainer, include_tags: Optional[set[str]], exclude_tags: Optional[set[str]]) -> None:
+    if not include_tags and not exclude_tags:
+        return
+
+    def _tag_ok(meta: dict) -> bool:
+        tags = set(meta.get("tags", ()))
+        if include_tags and not tags.intersection(include_tags):
+            return False
+        if exclude_tags and tags.intersection(exclude_tags):
+            return False
+        return True
+    container._providers = {k: v for k, v in container._providers.items() if _tag_ok(v)}
+
+def _compute_allowed_subgraph(container: PicoContainer, roots: Iterable[type]) -> set:
+    allowed: set[Any] = set(roots) # Start with roots
+    stack = list(roots or ())
+    # ... (rest of the function is the same, just ensure it's here)
+    def _add_impls_for_base(base_t):
+        for prov_key, meta in container._providers.items():
+            cls = prov_key if isinstance(prov_key, type) else None
+            if cls is not None and _is_compatible(cls, base_t):
+                if prov_key not in allowed:
+                    allowed.add(prov_key)
+                    stack.append(prov_key)
+
+    while stack:
+        k = stack.pop()
+        # if k in allowed: continue # Redundant, add() handles it
+        allowed.add(k)
+        if isinstance(k, type): _add_impls_for_base(k)
+        cls = k if isinstance(k, type) else None
+        if cls is None or not container.has(k): continue
+        try:
+            sig = _inspect.signature(cls.__init__)
+            hints = _get_hints(cls.__init__, owner_cls=cls)
+        except Exception:
+            continue
+        for pname, param in sig.parameters.items():
+            if pname == "self": continue
+            ann = hints.get(pname, param.annotation)
+            origin = get_origin(ann) or ann
+            if origin in (list, tuple):
+                inner = (get_args(ann) or (object,))[0]
+                if get_origin(inner) is Annotated: inner = (get_args(inner) or (object,))[0]
+                if isinstance(inner, type):
+                    if inner not in allowed:
+                        stack.append(inner)
+                continue
+            if isinstance(ann, type) and ann not in allowed:
+                stack.append(ann)
+            elif container.has(pname) and pname not in allowed:
+                stack.append(pname)
+    return allowed
+
+
+def _restrict_to_subgraph(container: PicoContainer, roots: Iterable[type], overrides: Optional[Dict[Any, Any]]) -> None:
+    allowed = _compute_allowed_subgraph(container, roots)
+    keep_keys: set[Any] = allowed | (set(overrides.keys()) if overrides else set())
+    container._providers = {k: v for k, v in container._providers.items() if k in keep_keys}
+
+def _activate_and_build_interceptors(
+    *, container: PicoContainer, interceptor_decls: list[tuple[Any, dict]], profiles: list[str],
+) -> None:
+    resolver = Resolver(container)
+    active: list[tuple[int, str, str, Any]] = []
+    activated_method_names: list[str] = []
+    activated_container_names: list[str] = []
+    skipped_debug: list[str] = []
+
+    def _interceptor_meta_active(meta: dict) -> bool:
+        profs = tuple(meta.get("profiles", ())) or ()
+        if profs and (not profiles or not any(p in profs for p in profiles)): return False
+        req_env = tuple(meta.get("require_env", ())) or ()
+        if req_env and not all(os.getenv(k) not in (None, "") for k in req_env): return False
+        pred = meta.get("predicate", None)
+        if callable(pred):
+            try:
+                if not bool(pred()): return False
+            except Exception:
+                logging.exception("Interceptor predicate failed; skipping")
+                return False
+        return True
+
+    def _looks_like_container_interceptor(inst: Any) -> bool:
+        return all(hasattr(inst, m) for m in ("on_resolve", "on_before_create", "on_after_create", "on_exception"))
+
+    for raw_obj, meta in interceptor_decls:
+        owner_cls, obj = (raw_obj[0], raw_obj[1]) if isinstance(raw_obj, tuple) and len(raw_obj) == 2 else (None, raw_obj)
+        qn = getattr(obj, "__qualname__", repr(obj))
+        if not _conditional_active(obj, profiles=profiles) or not _interceptor_meta_active(meta):
+            skipped_debug.append(f"skip:{qn}")
+            continue
+        try:
+            if isinstance(obj, type):
+                inst = resolver.create_instance(obj)
+            elif owner_cls is not None:
+                owner_inst = resolver.create_instance(owner_cls)
+                bound = obj.__get__(owner_inst, owner_cls)
+                kwargs = resolver.kwargs_for_callable(bound, owner_cls=owner_cls)
+                inst = bound(**kwargs)
+            else:
+                kwargs = resolver.kwargs_for_callable(obj, owner_cls=None)
+                inst = obj(**kwargs)
+        except Exception:
+            logging.exception("Failed to construct interceptor %r", obj)
+            continue
+        kind = meta.get("kind", "method")
+        if kind == "method" and not callable(inst):
+            logging.error("Interceptor %s is not valid for kind %s; skipping", qn, kind)
+            continue
+        if kind == "container" and not _looks_like_container_interceptor(inst):
+            logging.error("Container interceptor %s lacks required methods; skipping", qn)
+            continue
+        order = int(meta.get("order", 0))
+        active.append((order, qn, kind, inst))
+    
+    active.sort(key=lambda t: (t[0], t[1]))
+    
+    for _order, _qn, kind, inst in active:
+        if kind == "container":
+            container.add_container_interceptor(inst)
+            activated_container_names.append(_qn)
+        else:
+            container.add_method_interceptor(inst)
+            activated_method_names.append(_qn)
+
+    if activated_method_names or activated_container_names:
+        logging.info("Interceptors activated: method=%d, container=%d", len(activated_method_names), len(activated_container_names))
+        logging.debug("Activated method=%s; Activated container=%s", ", ".join(activated_method_names) or "-", ", ".join(activated_container_names) or "-")
+    if skipped_debug:
+        logging.debug("Skipped interceptors: %s", ", ".join(skipped_debug))

pico_ioc/container.py

@@ -1,11 +1,12 @@
-# pico_ioc/container.py
+# src/pico_ioc/container.py (Refactorizado)
 from __future__ import annotations
 import inspect
-from typing import Any, Dict, get_origin, get_args, Annotated
-import typing as _t 
-
+from typing import Any, Dict, get_origin, get_args, Annotated, Sequence, Optional, Callable, Union, Tuple
+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:
@@ -23,14 +24,35 @@ class Binder:
 
 
 class PicoContainer:
-    def __init__(self):
-        self._providers: Dict[Any, Dict[str, Any]] = {}
+    def __init__(self, providers: Dict[Any, Dict[str, Any]]):
+        self._providers = providers
         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()
+
+    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,)
+        
+    def binder(self) -> Binder:
+        """Returns a binder for this container."""
+        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:
@@ -43,25 +65,41 @@ class PicoContainer:
         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")
-
         prov = self._providers.get(key)
         if prov is None:
             raise NameError(f"No provider found for key {key!r}")
-
         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
 
@@ -82,13 +120,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 +129,9 @@ class PicoContainer:
                     matches.append(inst)
         return matches
 
+    def get_providers(self) -> Dict[Any, Dict]:
+        return self._providers.copy()
+
 
 def _is_protocol(t) -> bool:
     return getattr(t, "_is_protocol", False) is True
@@ -109,7 +145,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 +156,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 +176,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 +184,3 @@ def _requires_collection_of_base(cls, base) -> bool:
                 return True
     return False
 
-

pico_ioc/decorators.py

@@ -1,7 +1,7 @@
 # pico_ioc/decorators.py
 from __future__ import annotations
 import functools
-from typing import Any, Iterable
+from typing import Any, Iterable, Optional, Callable, Tuple, Literal
 
 COMPONENT_FLAG = "_is_component"
 COMPONENT_KEY = "_component_key"
@@ -17,6 +17,13 @@ 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__"
+
+
 def factory_component(cls):
     setattr(cls, FACTORY_FLAG, True)
     return cls
@@ -31,6 +38,7 @@ 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] = ()):
     def dec(fn):
         @functools.wraps(fn)
@@ -49,7 +57,7 @@ def plugin(cls):
 
 
 class Qualifier(str):
-    __slots__ = ()  # tiny memory win; immutable like str
+    __slots__ = ()
 
 
 def qualifier(*qs: Qualifier):
@@ -66,14 +74,61 @@ def qualifier(*qs: Qualifier):
     return dec
 
 
+def on_missing(selector: object, *, priority: int = 0):
+    def dec(obj):
+        setattr(obj, ON_MISSING_META, {"selector": selector, "priority": int(priority)})
+        return obj
+    return dec
+
+
+def primary(obj):
+    setattr(obj, PRIMARY_FLAG, True)
+    return obj
+
+
+def conditional(
+    *,
+    profiles: tuple[str, ...] = (),
+    require_env: tuple[str, ...] = (),
+    predicate: Optional[Callable[[], bool]] = None,
+):
+    def dec(obj):
+        setattr(obj, CONDITIONAL_META, {
+            "profiles": tuple(profiles),
+            "require_env": tuple(require_env),
+            "predicate": predicate,
+        })
+        return obj
+    return dec
+
+
+def interceptor(
+    _obj=None,
+    *,
+    kind: Literal["method", "container"] = "method",
+    order: int = 0,
+    profiles: Tuple[str, ...] = (),
+    require_env: Tuple[str, ...] = (),
+    predicate: Callable[[], bool] | None = None,
+):
+    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",
     "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", "primary", "conditional",
+    "ON_MISSING_META", "PRIMARY_FLAG", "CONDITIONAL_META",
+    "interceptor", "INTERCEPTOR_META",
 ]
 

pico_ioc/interceptors.py

@@ -0,0 +1,50 @@
+# pico_ioc/interceptors.py
+from __future__ import annotations
+from typing import Any, Callable, Protocol, Sequence
+import inspect
+
+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):
+    if inv.is_async:
+        # return a coroutine that the caller will await
+        return _chain_async(interceptors, inv, 0)
+    # return the final value directly for sync methods
+    res = _chain_sync(interceptors, inv, 0)
+    return res
+
+
+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)
+