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

pico_ioc/__init__.py

@@ -1,16 +1,25 @@
 # 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 .scope import ScopedContainer
+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
+from .config import (
+    config_component, EnvSource, FileSource,
+    Env, File, Path, Value,
+)
 
 __all__ = [
     "__version__",
@@ -18,15 +27,32 @@ __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",
+    "ScopedContainer",
+    "config_component", 
+    "EnvSource", 
+    "FileSource", 
+    "Env", 
+    "File", 
+    "Path", 
+    "Value",
 ]
 

pico_ioc/_state.py

@@ -1,10 +1,75 @@
-# pico_ioc/_state.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from threading import RLock
 from contextvars import ContextVar
-from typing import Optional
+from contextlib import contextmanager
+from typing import Optional, TYPE_CHECKING
+
+# Type-only import to avoid cycles
+if TYPE_CHECKING:
+    from .container import PicoContainer
+
+
+# ---- Task/process context for the active container ----
+
+@dataclass(frozen=True, slots=True)
+class ContainerContext:
+    """Immutable snapshot for the active container state."""
+    container: "PicoContainer"
+    fingerprint: tuple
+    root_name: Optional[str]
+
+
+# Process-wide fallback (for non-async code) guarded by a lock
+_lock = RLock()
+_current_context: Optional[ContainerContext] = None
+
+# Task-local context (for async isolation)
+_ctxvar: ContextVar[Optional[ContainerContext]] = ContextVar("pico_ioc_ctx", default=None)
+
+
+def get_context() -> Optional[ContainerContext]:
+    """Return the current context (task-local first, then process-global)."""
+    ctx = _ctxvar.get()
+    return ctx if ctx is not None else _current_context
+
+
+def set_context(ctx: Optional[ContainerContext]) -> None:
+    """Atomically set both task-local and process-global context."""
+    with _lock:
+        _ctxvar.set(ctx)
+        globals()["_current_context"] = ctx
+
+
+# Optional compatibility helpers (only used by legacy API paths)
+def get_fingerprint() -> Optional[tuple]:
+    ctx = get_context()
+    return ctx.fingerprint if ctx else None
+
+
+def set_fingerprint(fp: Optional[tuple]) -> None:
+    """Compatibility shim: setting None clears the active context."""
+    if fp is None:
+        set_context(None)
+        return
+    ctx = get_context()
+    if ctx is not None:
+        set_context(ContainerContext(container=ctx.container, fingerprint=fp, root_name=ctx.root_name))
+
+
+# ---- Scan/resolve guards (kept as-is) ----
 
 _scanning: ContextVar[bool] = ContextVar("pico_scanning", default=False)
 _resolving: ContextVar[bool] = ContextVar("pico_resolving", default=False)
 
-_container = None
-_root_name: Optional[str] = None
+
+@contextmanager
+def scanning_flag():
+    """Mark scanning=True within the block."""
+    tok = _scanning.set(True)
+    try:
+        yield
+    finally:
+        _scanning.reset(tok)
 

pico_ioc/_version.py

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

pico_ioc/api.py

@@ -1,289 +1,221 @@
-# 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
+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
+from .scope import ScopedContainer
+from .config import ConfigRegistry, ConfigSource
 
 
 def reset() -> None:
-    """Reset the global container."""
-    _state._container = None
-    _state._root_name = None
+    _state.set_context(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)
+
+# -------- 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)
+        elif name == "config":
+            cfg = locals_in_init.get("config") or ()
+            norm = []
+            for s in cfg:
+                try:
+                    if type(s).__name__ == "EnvSource":
+                        norm.append(("env", getattr(s, "prefix", "")))
+                    elif type(s).__name__ == "FileSource":
+                        norm.append(("file", str(getattr(s, "path", ""))))
+                    else:
+                        norm.append((type(s).__module__, type(s).__qualname__))
+                except Exception:
+                    norm.append(repr(s))
+            val = tuple(norm)
+        else:
+            val = _normalize_for_fp(val)
+        entries.append((name, val))
+    return tuple(sorted(entries))
+
+# -------- container reuse and caller exclusion helpers --------
+def _maybe_reuse_existing(fp: tuple, overrides: Optional[Dict[Any, Any]]) -> Optional[PicoContainer]:
+    ctx = _state.get_context()
+    if ctx and ctx.fingerprint == fp:
+        return ctx.container
+    return None
 
+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))
 
+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
+
+# ---------------- public API ----------------
 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,
+    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,
+    config: Sequence[ConfigSource] = (),
 ) -> PicoContainer:
-
     root_name = root_package if isinstance(root_package, str) else getattr(root_package, "__name__", None)
+    fp = _make_fingerprint_from_signature(locals())
 
-    if reuse and _state._container and _state._root_name == root_name:
-        if overrides:
-            _apply_overrides(_state._container, overrides)
-        return _state._container
+    if reuse:
+        reused = _maybe_reuse_existing(fp, overrides)
+        if reused is not None:
+            return reused
 
-    combined_exclude = _build_exclude(exclude, auto_exclude_caller, root_name=root_name)
+    builder = (PicoContainerBuilder()
+               .with_plugins(plugins)
+               .with_profiles(profiles)
+               .with_overrides(overrides)
+               .with_config(ConfigRegistry(config or ()))) 
 
-    container = PicoContainer()
-    binder = Binder(container)
-    logging.info("Initializing pico-ioc...")
+    combined_exclude = _build_exclude(exclude, auto_exclude_caller, root_name=root_name)
+    builder.add_scan_package(root_package, exclude=combined_exclude)
 
-    with _scanning_flag():
-        scan_and_configure(
-            root_package,
-            container,
-            exclude=combined_exclude,
-            plugins=plugins,
-        )
+    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()
+
+    # Activate new context atomically
+    new_ctx = _state.ContainerContext(container=container, fingerprint=fp, root_name=root_name)
+    _state.set_context(new_ctx)
+    return container
 
-    if overrides:
-        _apply_overrides(container, overrides)
+def scope(
+    *, 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:
+    builder = PicoContainerBuilder()
 
-    _run_hooks(plugins, "after_bind", container, binder)
-    _run_hooks(plugins, "before_eager", container, binder)
+    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", ())))
 
-    container.eager_instantiate_all()
+    builder.with_profiles(profiles)\
+           .with_overrides(overrides)\
+           .with_tag_filters(include=include_tags, exclude=exclude_tags)\
+           .with_roots(roots)
 
-    _run_hooks(plugins, "after_ready", container, binder)
+    for m in modules:
+        builder.add_scan_package(m)
 
-    logging.info("Container configured and ready.")
-    _state._container = container
-    _state._root_name = root_name
-    return container
+    built_container = builder.with_eager(not lazy).build()
 
+    scoped_container = ScopedContainer(base=base, strict=strict, built_container=built_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
-) -> 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
     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)
-
-
-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 scoped_container
 
-    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)
-        
-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
+def container_fingerprint() -> Optional[tuple]:
+    ctx = _state.get_context()
+    return ctx.fingerprint if ctx else None
 
-        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
-
-
-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
-
-    # no resource suppression; placeholder for future cleanup/shutdown
-    def __exit__(self, exc_type, exc, tb):
-        return False
-
-    def get(self, key: Any):
-        try:
-            return super().get(key)
-        except NameError as e:
-            if not self._strict and self._base is not None and self._base.has(key):
-                return self._base.get(key)
-            raise e