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

pico_ioc/__init__.py

@@ -5,6 +5,7 @@ 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,
@@ -15,6 +16,10 @@ from .resolver import Resolver
 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__",
@@ -41,5 +46,13 @@ __all__ = [
     "conditional",
     "interceptor",
     "Resolver",
+    "ScopedContainer",
+    "config_component", 
+    "EnvSource", 
+    "FileSource", 
+    "Env", 
+    "File", 
+    "Path", 
+    "Value",
 ]
 

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.4.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(
@@ -122,6 +135,7 @@ def init(
     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())
@@ -131,7 +145,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,9 +169,9 @@ def init(
 
     container = builder.build()
 
-    _state._container = container
-    _state._root_name = root_name
-    _state.set_fingerprint(fp)
+    # 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(
@@ -178,9 +196,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 +213,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,12 +1,12 @@
 # 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
@@ -14,9 +14,11 @@ 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:
+    """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] = {}
@@ -27,39 +29,54 @@ class PicoContainerBuilder:
         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
 
-    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
+
+    # -------- build --------
+
     def build(self) -> PicoContainer:
+        """Build and return a fully configured container."""
         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)
+        
         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)
@@ -69,9 +86,9 @@ class PicoContainerBuilder:
         _activate_and_build_interceptors(
             container=container,
             interceptor_decls=self._interceptor_decls,
-            profiles=requested_profiles
+            profiles=requested_profiles,
         )
-        
+
         binder = container.binder()
 
         if self._overrides:
@@ -79,24 +96,30 @@ class PicoContainerBuilder:
 
         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]:
+
+# ---------------- 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]
@@ -104,11 +127,13 @@ 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
@@ -120,12 +145,14 @@ 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) # 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
@@ -136,23 +163,29 @@ def _compute_allowed_subgraph(container: PicoContainer, roots: Iterable[type]) -
 
     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)
@@ -169,38 +202,46 @@ def _restrict_to_subgraph(container: PicoContainer, roots: Iterable[type], overr
     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],
+    *, 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] = []
+    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
+        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 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
+                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"))
+        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)
@@ -215,6 +256,7 @@ def _activate_and_build_interceptors(
         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)
@@ -222,21 +264,31 @@ def _activate_and_build_interceptors(
         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)
+            container.add_container_interceptor(inst)  # type: ignore[arg-type]
             activated_container_names.append(_qn)
         else:
-            container.add_method_interceptor(inst)
+            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 "-")
+        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))
+