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

pico_ioc/__init__.py

@@ -1,16 +1,20 @@
 # pico_ioc/__init__.py
-
 try:
     from ._version import __version__
 except Exception:
     __version__ = "0.0.0"
 
 from .container import PicoContainer, Binder
-from .decorators import component, factory_component, provides, plugin, Qualifier, qualifier
+from .decorators import (
+    component, factory_component, provides, plugin,
+    Qualifier, qualifier,
+    on_missing, primary, conditional, interceptor,
+)
 from .plugins import PicoPlugin
 from .resolver import Resolver
-from .api import init, reset, scope
-from .proxy import ComponentProxy
+from .api import init, reset, scope, container_fingerprint
+from .proxy import ComponentProxy, IoCProxy
+from .interceptors import Invocation, MethodInterceptor, ContainerInterceptor
 
 __all__ = [
     "__version__",
@@ -18,15 +22,24 @@ __all__ = [
     "Binder",
     "PicoPlugin",
     "ComponentProxy",
+    "IoCProxy",
+    "Invocation",
+    "MethodInterceptor",
+    "ContainerInterceptor",
     "init",
     "scope",
     "reset",
+    "container_fingerprint",
     "component",
     "factory_component",
     "provides",
     "plugin",
     "Qualifier",
     "qualifier",
+    "on_missing",
+    "primary",
+    "conditional",
+    "interceptor",
     "Resolver",
 ]
 

pico_ioc/_state.py

@@ -1,10 +1,40 @@
 # pico_ioc/_state.py
 from contextvars import ContextVar
 from typing import Optional
+from contextlib import contextmanager
 
 _scanning: ContextVar[bool] = ContextVar("pico_scanning", default=False)
 _resolving: ContextVar[bool] = ContextVar("pico_resolving", default=False)
 
 _container = None
 _root_name: Optional[str] = None
+_fingerprint: Optional[tuple] = None
+_fp_observed: bool = False
 
+@contextmanager
+def scanning_flag():
+    """Context manager: mark scanning=True within the block."""
+    tok = _scanning.set(True)
+    try:
+        yield
+    finally:
+        _scanning.reset(tok)
+
+# ---- fingerprint helpers (public via api) ----
+def set_fingerprint(fp: Optional[tuple]) -> None:
+    global _fingerprint
+    _fingerprint = fp
+
+def get_fingerprint() -> Optional[tuple]:
+    return _fingerprint
+    
+def reset_fp_observed() -> None:
+    global _fp_observed
+    _fp_observed = False
+
+def mark_fp_observed() -> None:
+    global _fp_observed
+    _fp_observed = True
+
+def was_fp_observed() -> bool:
+    return _fp_observed

pico_ioc/_version.py

@@ -1 +1 @@
-__version__ = '1.2.0'
+__version__ = '1.3.0'

pico_ioc/api.py

@@ -1,283 +1,231 @@
-# pico_ioc/api.py
-
+# src/pico_ioc/api.py
 from __future__ import annotations
 
-import inspect
+import inspect as _inspect
+import importlib
 import logging
-from contextlib import contextmanager
-from typing import Callable, Optional, Tuple, Any, Dict, Iterable
+import os
+from types import ModuleType
+from typing import Callable, Optional, Tuple, Any, Dict, Iterable, Sequence
 
-from .container import PicoContainer, Binder
+from .container import PicoContainer
 from .plugins import PicoPlugin
-from .scanner import scan_and_configure
 from . import _state
+from .builder import PicoContainerBuilder
 
-
+# The only helpers left are those directly related to the public API signature or fingerprinting
 def reset() -> None:
-    """Reset the global container."""
     _state._container = None
     _state._root_name = None
+    _state.set_fingerprint(None)
 
+def _combine_excludes(a: Optional[Callable[[str], bool]], b: Optional[Callable[[str], bool]]):
+    if not a and not b: return None
+    if a and not b: return a
+    if b and not a: return b
+    return lambda mod, _a=a, _b=b: _a(mod) or _b(mod)
 
-def init(
-    root_package,
-    *,
-    exclude: Optional[Callable[[str], bool]] = None,
-    auto_exclude_caller: bool = True,
-    plugins: Tuple[PicoPlugin, ...] = (),
-    reuse: bool = True,
-    overrides: Optional[Dict[Any, Any]] = None,
-) -> PicoContainer:
-
-    root_name = root_package if isinstance(root_package, str) else getattr(root_package, "__name__", None)
+# -------- fingerprint helpers --------
+def _callable_id(cb) -> tuple:
+    try:
+        mod = getattr(cb, "__module__", None)
+        qn = getattr(cb, "__qualname__", None)
+        code = getattr(cb, "__code__", None)
+        fn_line = getattr(code, "co_firstlineno", None) if code else None
+        return (mod, qn, fn_line)
+    except Exception:
+        return (repr(cb),)
+
+def _plugins_id(plugins: Tuple[PicoPlugin, ...]) -> tuple:
+    out = [(type(p).__module__, type(p).__qualname__) for p in plugins or ()]
+    return tuple(sorted(out))
+
+def _normalize_for_fp(value):
+    if isinstance(value, ModuleType):
+        return getattr(value, "__name__", repr(value))
+    if isinstance(value, (tuple, list)):
+        return tuple(_normalize_for_fp(v) for v in value)
+    if isinstance(value, set):
+        return tuple(sorted(_normalize_for_fp(v) for v in value))
+    if callable(value):
+        return ("callable",) + _callable_id(value)
+    return value
+
+_FP_EXCLUDE_KEYS = set()
+
+def _normalize_overrides_for_fp(overrides: Optional[Dict[Any, Any]]) -> tuple:
+    if not overrides:
+        return ()
+    items = []
+    for k, v in overrides.items():
+        nk = _normalize_for_fp(k)
+        nv = _normalize_for_fp(v)
+        items.append((nk, nv))
+    return tuple(sorted(items))
+
+def _make_fingerprint_from_signature(locals_in_init: dict) -> tuple:
+    sig = _inspect.signature(init)
+    entries = []
+    for name in sig.parameters.keys():
+        if name in _FP_EXCLUDE_KEYS: continue
+        if name == "root_package":
+            rp = locals_in_init.get("root_package")
+            root_name = rp if isinstance(rp, str) else getattr(rp, "__name__", None)
+            entries.append(("root", root_name))
+            continue
+        val = locals_in_init.get(name, None)
+        if name == "plugins":
+            val = _plugins_id(val or ())
+        elif name in ("profiles", "auto_scan"):
+            val = tuple(val or ())
+        elif name in ("exclude", "auto_scan_exclude"):
+            val = _callable_id(val) if val else None
+        elif name == "overrides":
+            val = _normalize_overrides_for_fp(val)
+        else:
+            val = _normalize_for_fp(val)
+        entries.append((name, val))
+    return tuple(sorted(entries))
 
-    if reuse and _state._container and _state._root_name == root_name:
-        if overrides:
-            _apply_overrides(_state._container, overrides)
+# -------- container reuse and caller exclusion helpers --------
+def _maybe_reuse_existing(fp: tuple, overrides: Optional[Dict[Any, Any]]) -> Optional[PicoContainer]:
+    if _state.get_fingerprint() == fp:
         return _state._container
+    return None
 
-    combined_exclude = _build_exclude(exclude, auto_exclude_caller, root_name=root_name)
+def _build_exclude(
+    exclude: Optional[Callable[[str], bool]], auto_exclude_caller: bool, *, root_name: Optional[str] = None
+) -> Optional[Callable[[str], bool]]:
+    if not auto_exclude_caller: return exclude
+    caller = _get_caller_module_name()
+    if not caller: return exclude
+    def _under_root(mod: str) -> bool:
+        return bool(root_name) and (mod == root_name or mod.startswith(root_name + "."))
+    if exclude is None:
+        return lambda mod, _caller=caller: (mod == _caller) and not _under_root(mod)
+    return lambda mod, _caller=caller, _prev=exclude: (((mod == _caller) and not _under_root(mod)) or _prev(mod))
 
-    container = PicoContainer()
-    binder = Binder(container)
-    logging.info("Initializing pico-ioc...")
+def _get_caller_module_name() -> Optional[str]:
+    try:
+        f = _inspect.currentframe()
+        # Stack: _get_caller -> _build_exclude -> init -> caller
+        if f and f.f_back and f.f_back.f_back and f.f_back.f_back.f_back:
+            mod = _inspect.getmodule(f.f_back.f_back.f_back)
+            return getattr(mod, "__name__", None)
+    except Exception:
+        pass
+    return None
 
-    with _scanning_flag():
-        scan_and_configure(
-            root_package,
-            container,
-            exclude=combined_exclude,
-            plugins=plugins,
-        )
+# ---------------- 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,
+    overrides: Optional[Dict[Any, Any]] = None, auto_scan: Sequence[str] = (),
+    auto_scan_exclude: Optional[Callable[[str], bool]] = None, strict_autoscan: bool = False,
+) -> PicoContainer:
+    root_name = root_package if isinstance(root_package, str) else getattr(root_package, "__name__", None)
+    fp = _make_fingerprint_from_signature(locals())
 
-    if overrides:
-        _apply_overrides(container, overrides)
+    if reuse:
+        reused = _maybe_reuse_existing(fp, overrides)
+        if reused is not None:
+            return reused
 
-    _run_hooks(plugins, "after_bind", container, binder)
-    _run_hooks(plugins, "before_eager", container, binder)
+    builder = PicoContainerBuilder().with_plugins(plugins).with_profiles(profiles).with_overrides(overrides)
 
-    container.eager_instantiate_all()
+    combined_exclude = _build_exclude(exclude, auto_exclude_caller, root_name=root_name)
+    builder.add_scan_package(root_package, exclude=combined_exclude)
 
-    _run_hooks(plugins, "after_ready", container, binder)
+    if auto_scan:
+        for pkg in auto_scan:
+            try:
+                mod = importlib.import_module(pkg)
+                scan_exclude = _combine_excludes(exclude, auto_scan_exclude)
+                builder.add_scan_package(mod, exclude=scan_exclude)
+            except ImportError as e:
+                msg = f"pico-ioc: auto_scan package not found: {pkg}"
+                if strict_autoscan:
+                    logging.error(msg)
+                    raise e
+                logging.warning(msg)
+
+    container = builder.build()
 
-    logging.info("Container configured and ready.")
     _state._container = container
     _state._root_name = root_name
+    _state.set_fingerprint(fp)
     return container
 
-
 def scope(
-    *,
-    modules: Iterable[Any] = (),
-    roots: Iterable[type] = (),
-    overrides: Optional[Dict[Any, Any]] = None,
-    base: Optional[PicoContainer] = None,
-    include: Optional[set[str]] = None,   # tag include (any-match)
-    exclude: Optional[set[str]] = None,   # tag exclude (any-match)
-    strict: bool = True,
-    lazy: bool = True,                    # if True -> do NOT instantiate roots here
+    *, modules: Iterable[Any] = (), roots: Iterable[type] = (), profiles: Optional[list[str]] = None,
+    overrides: Optional[Dict[Any, Any]] = None, base: Optional[PicoContainer] = None,
+    include_tags: Optional[set[str]] = None, exclude_tags: Optional[set[str]] = None,
+    strict: bool = True, lazy: bool = True,
 ) -> PicoContainer:
-    """
-    Build a lightweight container: scan, apply overrides, filter by tags, prune
-    to the dependency subgraph reachable from `roots`, and (optionally) instantiate roots.
-    - No global eager.
-    - If strict=False and base is provided, missing keys fall back to base.
-    """
-    c = _ScopedContainer(base=base, strict=strict)
-
-    logging.info("Initializing pico-ioc scope...")
-    with _scanning_flag():
-        for m in modules:
-            scan_and_configure(m, c, exclude=None, plugins=())
-
-    if overrides:
-        _apply_overrides(c, overrides)
-
-    # Tag filter (apply BEFORE reachability pruning)
-    def _tag_ok(meta: dict) -> bool:
-        if include and not set(include).intersection(meta.get("tags", ())):
-            return False
-        if exclude and set(exclude).intersection(meta.get("tags", ())):
-            return False
-        return True
-
-    c._providers = {k: v for k, v in c._providers.items() if _tag_ok(v)}  # type: ignore[attr-defined]
-
-    # Reachability from roots (subgraph) + keep overrides
-    allowed = _compute_allowed_subgraph(c, roots)
-    keep_keys: set[Any] = set(allowed) | (set(overrides.keys()) if overrides else set())
-    c._providers = {k: v for k, v in c._providers.items() if k in keep_keys}  # type: ignore[attr-defined]
-
-    # Instantiate roots only when NOT lazy
+    builder = PicoContainerBuilder()
+
+    if base is not None and not strict:
+        base_providers = getattr(base, "_providers", {})
+        builder._providers.update(base_providers)
+        if profiles is None:
+            builder.with_profiles(list(getattr(base, "_active_profiles", ())))
+
+    builder.with_profiles(profiles)\
+           .with_overrides(overrides)\
+           .with_tag_filters(include=include_tags, exclude=exclude_tags)\
+           .with_roots(roots)
+
+    for m in modules:
+        builder.add_scan_package(m)
+
+    built_container = builder.build()
+
+    scoped_container = _ScopedContainer(base=base, strict=strict, built_container=built_container)
+
     if not lazy:
         from .proxy import ComponentProxy
         for rk in roots or ():
             try:
-                obj = c.get(rk)
+                obj = scoped_container.get(rk)
                 if isinstance(obj, ComponentProxy):
                     _ = obj._get_real_object()
             except NameError:
-                if strict:
-                    raise
-                # non-strict: skip missing root
-                continue
+                if strict: raise
 
     logging.info("Scope container ready.")
-    return c
-
-# -------------------- helpers --------------------
-
-def _apply_overrides(container: PicoContainer, overrides: Dict[Any, Any]) -> None:
-    for key, val in overrides.items():
-        lazy = False
-        if isinstance(val, tuple) and len(val) == 2 and callable(val[0]) and isinstance(val[1], bool):
-            provider = val[0]
-            lazy = val[1]
-        elif callable(val):
-            provider = val
-        else:
-            def provider(v=val):
-                return v
-        container.bind(key, provider, lazy=lazy)
-
+    return scoped_container
 
-def _build_exclude(
-    exclude: Optional[Callable[[str], bool]],
-    auto_exclude_caller: bool,
-    *,
-    root_name: Optional[str] = None,
-) -> Optional[Callable[[str], bool]]:
-    if not auto_exclude_caller:
-        return exclude
-
-    caller = _get_caller_module_name()
-    if not caller:
-        return exclude
-
-    def _under_root(mod: str) -> bool:
-        return bool(root_name) and (mod == root_name or mod.startswith(root_name + "."))
-
-    if exclude is None:
-        return lambda mod, _caller=caller: (mod == _caller) and not _under_root(mod)
-
-    prev = exclude
-    return lambda mod, _caller=caller, _prev=prev: (((mod == _caller) and not _under_root(mod)) or _prev(mod))
-
-
-def _get_caller_module_name() -> Optional[str]:
-    try:
-        f = inspect.currentframe()
-        # frame -> _get_caller_module_name -> _build_exclude -> init
-        if f and f.f_back and f.f_back.f_back and f.f_back.f_back.f_back:
-            mod = inspect.getmodule(f.f_back.f_back.f_back)
-            return getattr(mod, "__name__", None)
-    except Exception:
-        pass
-    return None
-
-
-def _run_hooks(
-    plugins: Tuple[PicoPlugin, ...],
-    hook_name: str,
-    container: PicoContainer,
-    binder: Binder,
-) -> None:
-    for pl in plugins:
-        try:
-            fn = getattr(pl, hook_name, None)
-            if fn:
-                fn(container, binder)
-        except Exception:
-            logging.exception("Plugin %s failed", hook_name)
-
-
-@contextmanager
-def _scanning_flag():
-    tok = _state._scanning.set(True)
-    try:
-        yield
-    finally:
-        _state._scanning.reset(tok)
+class _ScopedContainer(PicoContainer):
+    def __init__(self, built_container: PicoContainer, base: Optional[PicoContainer], strict: bool):
+        super().__init__(providers=getattr(built_container, "_providers", {}).copy())
         
-def _compute_allowed_subgraph(container: PicoContainer, roots: Iterable[type]) -> set:
-    """
-    Traverse constructor annotations from roots to collect reachable provider keys.
-    Includes implementations for collection injections (list[T]/tuple[T]).
-    """
-    from .resolver import _get_hints
-    from .container import _is_compatible  # structural / subclass check
-    import inspect
-    from typing import get_origin, get_args, Annotated
-
-    allowed: set[Any] = set()
-    stack = list(roots or ())
-
-    # Helper: add all provider keys whose class is compatible with `base`
-    def _add_impls_for_base(base_t):
-        for prov_key, meta in container._providers.items():  # type: ignore[attr-defined]
-            cls = prov_key if isinstance(prov_key, type) else None
-            if cls is None:
-                continue
-            if _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
-        allowed.add(k)
-
-        cls = k if isinstance(k, type) else None
-        if cls is None or not container.has(k):
-            # not a class or not currently bound → no edges to follow
-            continue
-
-        try:
-            sig = inspect.signature(cls.__init__)
-        except Exception:
-            continue
-
-        hints = _get_hints(cls.__init__, owner_cls=cls)
-        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]
-                # We don’t know exact impls yet, so:
-                if isinstance(inner, type):
-                    # keep the base “type” in allowed for clarity
-                    allowed.add(inner)
-                    # And include ALL implementations present in providers
-                    _add_impls_for_base(inner)
-                continue
-
-            if isinstance(ann, type):
-                stack.append(ann)
-            elif container.has(pname):
-                stack.append(pname)
-
-    return allowed
+        self._active_profiles = getattr(built_container, "_active_profiles", ())
+        
+        base_method_its = getattr(base, "_method_interceptors", ()) if base else ()
+        base_container_its = getattr(base, "_container_interceptors", ()) if base else ()
+        
+        self._method_interceptors = base_method_its
+        self._container_interceptors = base_container_its
+        self._seen_interceptor_types = {type(it) for it in (base_method_its + base_container_its)}
 
+        for it in getattr(built_container, "_method_interceptors", ()):
+            self.add_method_interceptor(it)
+        for it in getattr(built_container, "_container_interceptors", ()):
+            self.add_container_interceptor(it)
 
-class _ScopedContainer(PicoContainer):
-    def __init__(self, base: Optional[PicoContainer], strict: bool):
-        super().__init__()
         self._base = base
         self._strict = strict
 
-    # allow `with pico_ioc.scope(...) as c:`
-    def __enter__(self):
-        return self
+        if base:
+            self._singletons.update(getattr(base, "_singletons", {}))
 
-    # no resource suppression; placeholder for future cleanup/shutdown
-    def __exit__(self, exc_type, exc, tb):
+    def __enter__(self): return self
+    def __exit__(self, exc_type, exc, tb): return False
+
+    def has(self, key: Any) -> bool:
+        if super().has(key): return True
+        if not self._strict and self._base is not None:
+            return self._base.has(key)
         return False
 
     def get(self, key: Any):
@@ -287,3 +235,6 @@ class _ScopedContainer(PicoContainer):
             if not self._strict and self._base is not None and self._base.has(key):
                 return self._base.get(key)
             raise e
+
+def container_fingerprint() -> Optional[tuple]:
+    return _state.get_fingerprint()