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

pico_ioc/__init__.py

@@ -1,20 +1,31 @@
-# pico_ioc/__init__.py
 try:
     from ._version import __version__
 except Exception:
     __version__ = "0.0.0"
 
 from .container import PicoContainer, Binder
+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__",
@@ -23,9 +34,11 @@ __all__ = [
     "PicoPlugin",
     "ComponentProxy",
     "IoCProxy",
-    "Invocation",
     "MethodInterceptor",
     "ContainerInterceptor",
+    "MethodCtx",
+    "ResolveCtx",
+    "CreateCtx",
     "init",
     "scope",
     "reset",
@@ -39,7 +52,17 @@ __all__ = [
     "on_missing",
     "primary",
     "conditional",
-    "interceptor",
+    "infrastructure",
     "Resolver",
+    "ScopedContainer",
+    "config_component",
+    "EnvSource",
+    "FileSource",
+    "Env",
+    "File",
+    "Path",
+    "Value",
+    "Infra",
+    "Select",
 ]
 

pico_ioc/_state.py

@@ -1,40 +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
-_fingerprint: Optional[tuple] = None
-_fp_observed: bool = False
 
 @contextmanager
 def scanning_flag():
-    """Context manager: mark scanning=True within the block."""
+    """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.3.0'
+__version__ = '1.5.0'

pico_ioc/api.py

@@ -1,10 +1,8 @@
-# src/pico_ioc/api.py
 from __future__ import annotations
 
 import inspect as _inspect
 import importlib
 import logging
-import os
 from types import ModuleType
 from typing import Callable, Optional, Tuple, Any, Dict, Iterable, Sequence
 
@@ -12,12 +10,12 @@ from .container import PicoContainer
 from .plugins import PicoPlugin
 from . import _state
 from .builder import PicoContainerBuilder
+from .scope import ScopedContainer
+from .config import ConfigRegistry, ConfigSource
+
 
-# The only helpers left are those directly related to the public API signature or fingerprinting
 def reset() -> None:
-    _state._container = None
-    _state._root_name = None
-    _state.set_fingerprint(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
@@ -82,6 +80,20 @@ def _make_fingerprint_from_signature(locals_in_init: dict) -> tuple:
             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))
@@ -89,8 +101,9 @@ def _make_fingerprint_from_signature(locals_in_init: dict) -> tuple:
 
 # -------- 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
+    ctx = _state.get_context()
+    if ctx and ctx.fingerprint == fp:
+        return ctx.container
     return None
 
 def _build_exclude(
@@ -116,13 +129,15 @@ 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,
     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:
+    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())
 
@@ -131,7 +146,11 @@ def init(
         if reused is not None:
             return reused
 
-    builder = PicoContainerBuilder().with_plugins(plugins).with_profiles(profiles).with_overrides(overrides)
+    builder = (PicoContainerBuilder()
+               .with_plugins(plugins)
+               .with_profiles(profiles)
+               .with_overrides(overrides)
+               .with_config(ConfigRegistry(config or ()))) 
 
     combined_exclude = _build_exclude(exclude, auto_exclude_caller, root_name=root_name)
     builder.add_scan_package(root_package, exclude=combined_exclude)
@@ -151,11 +170,11 @@ def init(
 
     container = builder.build()
 
-    _state._container = container
-    _state._root_name = root_name
-    _state.set_fingerprint(fp)
+    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,
@@ -178,9 +197,9 @@ def scope(
     for m in modules:
         builder.add_scan_package(m)
 
-    built_container = builder.build()
+    built_container = builder.with_eager(not lazy).build()
 
-    scoped_container = _ScopedContainer(base=base, strict=strict, built_container=built_container)
+    scoped_container = ScopedContainer(base=base, strict=strict, built_container=built_container)
 
     if not lazy:
         from .proxy import ComponentProxy
@@ -195,46 +214,9 @@ def scope(
     logging.info("Scope container ready.")
     return scoped_container
 
-class _ScopedContainer(PicoContainer):
-    def __init__(self, built_container: PicoContainer, base: Optional[PicoContainer], strict: bool):
-        super().__init__(providers=getattr(built_container, "_providers", {}).copy())
-        
-        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)
-
-        self._base = base
-        self._strict = strict
-
-        if base:
-            self._singletons.update(getattr(base, "_singletons", {}))
-
-    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):
-        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
+
 
 def container_fingerprint() -> Optional[tuple]:
-    return _state.get_fingerprint()
+    ctx = _state.get_context()
+    return ctx.fingerprint if ctx else None
+

pico_ioc/builder.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/builder.py
 from __future__ import annotations
 import inspect as _inspect
 import logging
@@ -6,7 +5,6 @@ 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
@@ -14,7 +12,7 @@ from .plugins import PicoPlugin, run_plugin_hook
 from .scanner import scan_and_configure
 from .resolver import Resolver, _get_hints
 from . import _state
-
+from .config import ConfigRegistry
 
 class PicoContainerBuilder:
     def __init__(self):
@@ -26,72 +24,70 @@ 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
+
+    def with_config(self, registry: ConfigRegistry) -> "PicoContainerBuilder":
+        self._config_registry = registry
+        return self
 
-    def with_plugins(self, plugins: Tuple[PicoPlugin, ...]) -> PicoContainerBuilder:
-        self._plugins = plugins
+    def with_plugins(self, plugins: Tuple[PicoPlugin, ...]) -> "PicoContainerBuilder":
+        self._plugins = plugins or ()
         return self
 
-    def with_profiles(self, profiles: Optional[List[str]]) -> PicoContainerBuilder:
+    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:
+    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:
+    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:
+    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
+    def with_roots(self, roots: Iterable[type]) -> "PicoContainerBuilder":
+        self._roots = roots or ()
+        return self
+
+    def with_eager(self, eager: bool) -> "PicoContainerBuilder":
+        self._eager = bool(eager)
         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)
-
+        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)
-        container.eager_instantiate_all()
+        if self._eager:
+            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]:
+def _resolve_profiles(profiles: Optional[List[str]]) -> List[str]:
     if profiles is not None:
         return list(profiles)
     env_val = os.getenv("PICO_PROFILE", "")
@@ -112,7 +108,6 @@ def _apply_overrides(container: PicoContainer, overrides: Dict[Any, Any]) -> Non
 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):
@@ -123,9 +118,8 @@ def _filter_by_tags(container: PicoContainer, include_tags: Optional[set[str]],
     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
+    allowed: set[Any] = set(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
@@ -133,26 +127,28 @@ 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()
-        # if k in allowed: continue # Redundant, add() handles it
         allowed.add(k)
-        if isinstance(k, type): _add_impls_for_base(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
+        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
+            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 get_origin(inner) is Annotated:
+                    inner = (get_args(inner) or (object,))[0]
                 if isinstance(inner, type):
                     if inner not in allowed:
                         stack.append(inner)
@@ -163,80 +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
+        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
+                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)
+            import logging
+            logging.exception("Failed to construct infrastructure %r", cls)
             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))
+        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)
+