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

pico_ioc/__init__.py

@@ -1,4 +1,3 @@
-# pico_ioc/__init__.py
 try:
     from ._version import __version__
 except Exception:
@@ -9,17 +8,24 @@ from .scope import ScopedContainer
 from .decorators import (
     component, factory_component, provides, plugin,
     Qualifier, qualifier,
-    on_missing, primary, conditional, interceptor,
+    on_missing, primary, conditional, infrastructure,
 )
 from .plugins import PicoPlugin
 from .resolver import Resolver
 from .api import init, reset, scope, container_fingerprint
 from .proxy import ComponentProxy, IoCProxy
-from .interceptors import Invocation, MethodInterceptor, ContainerInterceptor
+from .interceptors import (
+    MethodInterceptor,
+    ContainerInterceptor,
+    MethodCtx,
+    ResolveCtx,
+    CreateCtx,
+)
 from .config import (
     config_component, EnvSource, FileSource,
     Env, File, Path, Value,
 )
+from .infra import Infra, Select
 
 __all__ = [
     "__version__",
@@ -28,9 +34,11 @@ __all__ = [
     "PicoPlugin",
     "ComponentProxy",
     "IoCProxy",
-    "Invocation",
     "MethodInterceptor",
     "ContainerInterceptor",
+    "MethodCtx",
+    "ResolveCtx",
+    "CreateCtx",
     "init",
     "scope",
     "reset",
@@ -44,15 +52,17 @@ __all__ = [
     "on_missing",
     "primary",
     "conditional",
-    "interceptor",
+    "infrastructure",
     "Resolver",
     "ScopedContainer",
-    "config_component", 
-    "EnvSource", 
-    "FileSource", 
-    "Env", 
-    "File", 
-    "Path", 
+    "config_component",
+    "EnvSource",
+    "FileSource",
+    "Env",
+    "File",
+    "Path",
     "Value",
+    "Infra",
+    "Select",
 ]
 

pico_ioc/_version.py

@@ -1 +1 @@
-__version__ = '1.4.0'
+__version__ = '1.5.0'

pico_ioc/api.py

@@ -129,7 +129,6 @@ def _get_caller_module_name() -> Optional[str]:
         pass
     return None
 
-# ---------------- public API ----------------
 def init(
     root_package, *, profiles: Optional[list[str]] = None, exclude: Optional[Callable[[str], bool]] = None,
     auto_exclude_caller: bool = True, plugins: Tuple[PicoPlugin, ...] = (), reuse: bool = True,
@@ -137,6 +136,8 @@ def init(
     auto_scan_exclude: Optional[Callable[[str], bool]] = None, strict_autoscan: bool = False,
     config: Sequence[ConfigSource] = (),
 ) -> PicoContainer:
+    if _state._scanning.get():
+        logging.info("re-entrant container access during scan")
     root_name = root_package if isinstance(root_package, str) else getattr(root_package, "__name__", None)
     fp = _make_fingerprint_from_signature(locals())
 
@@ -169,11 +170,11 @@ def init(
 
     container = builder.build()
 
-    # Activate new context atomically
     new_ctx = _state.ContainerContext(container=container, fingerprint=fp, root_name=root_name)
     _state.set_context(new_ctx)
     return container
 
+
 def scope(
     *, modules: Iterable[Any] = (), roots: Iterable[type] = (), profiles: Optional[list[str]] = None,
     overrides: Optional[Dict[Any, Any]] = None, base: Optional[PicoContainer] = None,

pico_ioc/builder.py

@@ -1,6 +1,4 @@
-# src/pico_ioc/builder.py
 from __future__ import annotations
-
 import inspect as _inspect
 import logging
 import os
@@ -17,8 +15,6 @@ from . import _state
 from .config import ConfigRegistry
 
 class PicoContainerBuilder:
-    """Configures and builds a PicoContainer. Does not touch global context."""
-
     def __init__(self):
         self._scan_plan: List[Tuple[Any, Optional[Callable[[str], bool]], Tuple[PicoPlugin, ...]]] = []
         self._overrides: Dict[Any, Any] = {}
@@ -28,12 +24,9 @@ class PicoContainerBuilder:
         self._exclude_tags: Optional[set[str]] = None
         self._roots: Iterable[type] = ()
         self._providers: Dict[Any, Dict] = {}
-        self._interceptor_decls: List[Tuple[Any, dict]] = []
         self._eager: bool = True
         self._config_registry: ConfigRegistry | None = None
 
-    # -------- fluent config --------
-
     def with_config(self, registry: ConfigRegistry) -> "PicoContainerBuilder":
         self._config_registry = registry
         return self
@@ -67,59 +60,39 @@ class PicoContainerBuilder:
         self._eager = bool(eager)
         return self
 
-    # -------- build --------
-
     def build(self) -> PicoContainer:
-        """Build and return a fully configured container."""
         requested_profiles = _resolve_profiles(self._profiles)
-
         container = PicoContainer(providers=self._providers)
         container._active_profiles = tuple(requested_profiles)
         setattr(container, "_config_registry", self._config_registry)
-        
+        all_infras: list[tuple[type, dict]] = []
         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)
+                c, f, infra_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,
-        )
-
+                all_infras.extend(infra_decls)
+        _run_infrastructure(container=container, infra_decls=all_infras, 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)
-
         if self._eager:
             container.eager_instantiate_all()
         logging.info("Container configured and ready.")
         return container
 
-
-# ---------------- 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]
@@ -127,17 +100,14 @@ def _as_provider(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):
@@ -145,14 +115,11 @@ def _filter_by_tags(container: PicoContainer, include_tags: Optional[set[str]],
         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)
     stack = list(roots or ())
-
     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
@@ -160,23 +127,19 @@ def _compute_allowed_subgraph(container: PicoContainer, roots: Iterable[type]) -
                 if prov_key not in allowed:
                     allowed.add(prov_key)
                     stack.append(prov_key)
-
     while stack:
         k = stack.pop()
         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
@@ -196,99 +159,52 @@ def _compute_allowed_subgraph(container: PicoContainer, roots: Iterable[type]) -
                 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:
+def _run_infrastructure(*, container: PicoContainer, infra_decls: List[tuple[type, dict]], profiles: List[str]) -> None:
+    def _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
+        if req_env:
+            import os
+            if 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}")
+    from .resolver import Resolver
+    from .infra import Infra
+    resolver = Resolver(container)
+    active_infras: List[tuple[int, type]] = []
+    for cls, meta in infra_decls:
+        if not _active(meta):
             continue
-
+        order = int(meta.get("order", 0))
+        active_infras.append((order, cls))
+    active_infras.sort(key=lambda t: (t[0], getattr(t[1], "__qualname__", "")))
+    for _ord, cls in active_infras:
         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)
+            inst = resolver.create_instance(cls)
         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)
+            import logging
+            logging.exception("Failed to construct infrastructure %r", cls)
             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)  # type: ignore[arg-type]
-            activated_container_names.append(_qn)
-        else:
-            container.add_method_interceptor(inst)  # type: ignore[arg-type]
-            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))
+        infra = Infra(container=container, profiles=tuple(profiles))
+        fn = getattr(inst, "configure", None)
+        if callable(fn):
+            try:
+                fn(infra)
+            except Exception:
+                import logging
+                logging.exception("Infrastructure configure() failed for %r", cls)
 

pico_ioc/container.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/container.py
 from __future__ import annotations
 
 import inspect
@@ -6,11 +5,10 @@ from typing import Any, Dict, get_origin, get_args, Annotated
 import typing as _t
 
 from .proxy import IoCProxy
-from .interceptors import MethodInterceptor, ContainerInterceptor
+from .interceptors import MethodInterceptor, ContainerInterceptor, MethodCtx, ResolveCtx, CreateCtx, run_resolve_chain, run_create_chain
 from .decorators import QUALIFIERS_KEY
 from . import _state
 
-
 class Binder:
     def __init__(self, container: PicoContainer):
         self._c = container
@@ -24,7 +22,6 @@ class Binder:
     def get(self, key: Any):
         return self._c.get(key)
 
-
 class PicoContainer:
     def __init__(self, providers: Dict[Any, Dict[str, Any]] | None = None):
         self._providers = providers or {}
@@ -33,14 +30,9 @@ class PicoContainer:
         self._container_interceptors: tuple[ContainerInterceptor, ...] = ()
         self._active_profiles: tuple[str, ...] = ()
         self._seen_interceptor_types: set[type] = set()
-
-    # --- interceptors ---
+        self._method_cap: int | None = None
 
     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:
@@ -50,7 +42,8 @@ class PicoContainer:
         self._seen_interceptor_types.add(t)
         self._container_interceptors = self._container_interceptors + (it,)
 
-    # --- binding ---
+    def set_method_cap(self, n: int | None) -> None:
+        self._method_cap = (int(n) if n is not None else None)
 
     def binder(self) -> Binder:
         return Binder(self)
@@ -66,65 +59,44 @@ 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 _notify_resolve(self, key: Any, ann: Any, quals: tuple[str, ...] | tuple()):
+        ctx = ResolveCtx(key=key, qualifiers={q: True for q in quals or ()}, requested_by=None, profiles=self._active_profiles)
+        run_resolve_chain(self._container_interceptors, ctx)
+
     def get(self, key: Any):
         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]
-
-        for ci in self._container_interceptors:
-            try:
-                ci.on_before_create(key)
-            except Exception:
-                pass
-
+        def base_provider():
+            return prov["factory"]()
+        cls = key if isinstance(key, type) else None
+        ctx = CreateCtx(key=key, component=cls, provider=base_provider, profiles=self._active_profiles)
         tok = _state._resolving.set(True)
         try:
-            try:
-                instance = prov["factory"]()
-            except BaseException as exc:
-                for ci in self._container_interceptors:
-                    try:
-                        ci.on_exception(key, exc)
-                    except Exception:
-                        pass
-                raise
+            instance = run_create_chain(self._container_interceptors, ctx)
         finally:
             _state._resolving.reset(tok)
-
         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
-
+            chain = self._method_interceptors
+            cap = getattr(self, "_method_cap", None)
+            if isinstance(cap, int) and cap >= 0:
+                chain = chain[:cap]
+            instance = IoCProxy(instance, chain, container=self, request_key=key)
         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=()))
 
@@ -149,20 +121,15 @@ class PicoContainer:
     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
 
-
 def _is_compatible(cls, base) -> bool:
     try:
         if isinstance(base, type) and issubclass(cls, base):
             return True
     except TypeError:
         pass
-
     if _is_protocol(base):
         names = set(getattr(base, "__annotations__", {}).keys())
         names.update(n for n in getattr(base, "__dict__", {}).keys() if not n.startswith("_"))
@@ -172,22 +139,18 @@ def _is_compatible(cls, base) -> bool:
             if not hasattr(cls, n):
                 return False
         return True
-
     return False
 
-
 def _requires_collection_of_base(cls, base) -> bool:
     try:
         sig = inspect.signature(cls.__init__)
     except Exception:
         return False
-
     try:
         from .resolver import _get_hints
         hints = _get_hints(cls.__init__, owner_cls=cls)
     except Exception:
         hints = {}
-
     for name, param in sig.parameters.items():
         if name == "self":
             continue