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

pico_ioc/config.py

@@ -0,0 +1,332 @@
+# src/pico_ioc/config.py
+from __future__ import annotations
+
+import os, json, configparser, pathlib
+from dataclasses import is_dataclass, fields, MISSING
+from typing import Any, Callable, Dict, Iterable, Optional, Sequence, Tuple, Protocol
+
+# ---- Flags & metadata on classes / fields ----
+_CONFIG_FLAG = "_pico_is_config_component"
+_CONFIG_PREFIX = "_pico_config_prefix"
+_FIELD_META = "_pico_config_field_meta"  # dict: name -> FieldSpec
+
+# ---- Source protocol & implementations ----
+
+class ConfigSource(Protocol):
+    def get(self, key: str) -> Optional[str]: ...
+    def keys(self) -> Iterable[str]: ...
+
+class EnvSource:
+    def __init__(self, prefix: str = ""):
+        self.prefix = prefix or ""
+    def get(self, key: str) -> Optional[str]:
+        # try PREFIX+KEY first, then KEY
+        v = os.getenv(self.prefix + key)
+        if v is not None:
+            return v
+        return os.getenv(key)
+    def keys(self) -> Iterable[str]:
+        # best-effort; env keys only (without prefix expansion)
+        return os.environ.keys()
+
+class FileSource:
+    def __init__(self, path: os.PathLike[str] | str, optional: bool = False):
+        self.path = str(path)
+        self.optional = bool(optional)
+        self._cache: Dict[str, Any] = {}
+        self._load_once()
+
+    def _load_once(self):
+        p = pathlib.Path(self.path)
+        if not p.exists():
+            if self.optional:
+                self._cache = {}
+                return
+            raise FileNotFoundError(self.path)
+        text = p.read_text(encoding="utf-8")
+
+        # Try in order: JSON, INI, dotenv, YAML (if available)
+        # JSON
+        try:
+            data = json.loads(text)
+            self._cache = _flatten_obj(data)
+            return
+        except Exception:
+            pass
+        # INI
+        try:
+            cp = configparser.ConfigParser()
+            cp.read_string(text)
+            data = {s: dict(cp.items(s)) for s in cp.sections()}
+            # also root-level keys under DEFAULT
+            data.update(dict(cp.defaults()))
+            self._cache = _flatten_obj(data)
+            return
+        except Exception:
+            pass
+        # dotenv (simple KEY=VALUE per line)
+        try:
+            kv = {}
+            for line in text.splitlines():
+                line = line.strip()
+                if not line or line.startswith("#"): 
+                    continue
+                if "=" in line:
+                    k, v = line.split("=", 1)
+                    kv[k.strip()] = _strip_quotes(v.strip())
+            self._cache = _flatten_obj(kv)
+            if self._cache:
+                return
+        except Exception:
+            pass
+        # YAML if available
+        try:
+            import yaml  # type: ignore
+            data = yaml.safe_load(text) or {}
+            self._cache = _flatten_obj(data)
+            return
+        except Exception:
+            # if everything fails, fallback to empty (optional) or raise
+            if self.optional:
+                self._cache = {}
+                return
+            raise ValueError(f"Unrecognized file format: {self.path}")
+
+    def get(self, key: str) -> Optional[str]:
+        v = self._cache.get(key)
+        return None if v is None else str(v)
+
+    def keys(self) -> Iterable[str]:
+        return self._cache.keys()
+
+# ---- Field specs (overrides) ----
+
+class FieldSpec:
+    __slots__ = ("sources", "keys", "default", "path_is_dot")
+    def __init__(self, *, sources: Tuple[str, ...], keys: Tuple[str, ...], default: Any, path_is_dot: bool):
+        self.sources = sources
+        self.keys = keys
+        self.default = default
+        self.path_is_dot = path_is_dot  # true when keys are dotted-paths for structured files
+
+class _ValueSentinel:
+    def __getitem__(self, key_default: str | Tuple[str, Any], /):
+        if isinstance(key_default, tuple):
+            key, default = key_default
+        else:
+            key, default = key_default, MISSING
+        # default sources order env>file unless overridden in Value(...)
+        return _ValueFactory(key, default)
+Value = _ValueSentinel()
+
+class _ValueFactory:
+    def __init__(self, key: str, default: Any):
+        self.key = key
+        self.default = default
+    def __call__(self, *, sources: Tuple[str, ...] = ("env","file")):
+        return FieldSpec(sources=tuple(sources), keys=(self.key,), default=self.default, path_is_dot=False)
+
+class _EnvSentinel:
+    def __getitem__(self, key_default: str | Tuple[str, Any], /):
+        key, default = (key_default if isinstance(key_default, tuple) else (key_default, MISSING))
+        return FieldSpec(sources=("env",), keys=(key,), default=default, path_is_dot=False)
+Env = _EnvSentinel()
+
+class _FileSentinel:
+    def __getitem__(self, key_default: str | Tuple[str, Any], /):
+        key, default = (key_default if isinstance(key_default, tuple) else (key_default, MISSING))
+        return FieldSpec(sources=("file",), keys=(key,), default=default, path_is_dot=False)
+File = _FileSentinel()
+
+class _PathSentinel:
+    class _FilePath:
+        def __getitem__(self, key_default: str | Tuple[str, Any], /):
+            key, default = (key_default if isinstance(key_default, tuple) else (key_default, MISSING))
+            return FieldSpec(sources=("file",), keys=(key,), default=default, path_is_dot=True)
+    file = _FilePath()
+Path = _PathSentinel()
+
+# ---- Class decorator ----
+
+def config_component(*, prefix: str = ""):
+    def dec(cls):
+        setattr(cls, _CONFIG_FLAG, True)
+        setattr(cls, _CONFIG_PREFIX, prefix or "")
+        if not hasattr(cls, _FIELD_META):
+            setattr(cls, _FIELD_META, {})
+        return cls
+    return dec
+
+def is_config_component(cls: type) -> bool:
+    return bool(getattr(cls, _CONFIG_FLAG, False))
+
+# ---- Registry / resolution ----
+
+class ConfigRegistry:
+    """Holds ordered sources and provides typed resolution for @config_component classes."""
+    def __init__(self, sources: Sequence[ConfigSource]):
+        self.sources = tuple(sources or ())
+
+    def resolve(self, keys: Iterable[str]) -> Optional[str]:
+        # try each key across sources in order
+        for key in keys:
+            for src in self.sources:
+                v = src.get(key)
+                if v is not None:
+                    return v
+        return None
+
+def register_field_spec(cls: type, name: str, spec: FieldSpec) -> None:
+    meta: Dict[str, FieldSpec] = getattr(cls, _FIELD_META, None) or {}
+    meta[name] = spec
+    setattr(cls, _FIELD_META, meta)
+
+def build_component_instance(cls: type, registry: ConfigRegistry) -> Any:
+    prefix = getattr(cls, _CONFIG_PREFIX, "")
+    overrides: Dict[str, FieldSpec] = getattr(cls, _FIELD_META, {}) or {}
+
+    if is_dataclass(cls):
+        kwargs = {}
+        for f in fields(cls):
+            name = f.name
+            spec = overrides.get(name)
+            if spec:
+                val = _resolve_with_spec(spec, registry)
+            else:
+                # auto: PREFIX+NAME or NAME (env), NAME (file)
+                val = registry.resolve((prefix + name.upper(), name.upper()))
+                if val is None and f.default is not MISSING:
+                    val = f.default
+                elif val is None and f.default_factory is not MISSING:  # type: ignore
+                    val = f.default_factory()  # type: ignore
+            if val is None and f.default is MISSING and getattr(f, "default_factory", MISSING) is MISSING:  # type: ignore
+                raise NameError(f"Missing config for field {cls.__name__}.{name}")
+            kwargs[name] = _coerce_type(val, f.type)
+        return cls(**kwargs)
+
+    # Non-dataclass: inspect __init__ signature
+    import inspect
+    sig = inspect.signature(cls.__init__)
+    hints = _get_type_hints_safe(cls.__init__, owner=cls)
+    kwargs = {}
+    for pname, par in sig.parameters.items():
+        if pname == "self" or par.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+        ann = hints.get(pname, par.annotation)
+        spec = overrides.get(pname)
+        if spec:
+            val = _resolve_with_spec(spec, registry)
+        else:
+            val = registry.resolve((prefix + pname.upper(), pname.upper()))
+            if val is None and par.default is not inspect._empty:
+                val = par.default
+        if val is None and par.default is inspect._empty:
+            raise NameError(f"Missing config for field {cls.__name__}.{pname}")
+        kwargs[pname] = _coerce_type(val, ann)
+    return cls(**kwargs)
+
+# ---- helpers ----
+
+def _resolve_with_spec(spec: FieldSpec, registry: ConfigRegistry) -> Any:
+    # respect spec.sources ordering, but try all keys for each source
+    for src_kind in spec.sources:
+        if src_kind == "env":
+            v = _resolve_from_sources(registry, spec.keys, predicate=lambda s: isinstance(s, EnvSource))
+        elif src_kind == "file":
+            if spec.path_is_dot:
+                v = _resolve_path_from_files(registry, spec.keys)
+            else:
+                v = _resolve_from_sources(registry, spec.keys, predicate=lambda s: isinstance(s, FileSource))
+        else:
+            v = None
+        if v is not None:
+            return v
+    return None if spec.default is MISSING else spec.default
+
+def _resolve_from_sources(registry: ConfigRegistry, keys: Tuple[str, ...], predicate: Callable[[ConfigSource], bool]) -> Optional[str]:
+    for key in keys:
+        for src in registry.sources:
+            if predicate(src):
+                v = src.get(key)
+                if v is not None:
+                    return v
+    return None
+
+def _resolve_path_from_files(registry: ConfigRegistry, dotted_keys: Tuple[str, ...]) -> Optional[str]:
+    for key in dotted_keys:
+        path = key.split(".")
+        for src in registry.sources:
+            if isinstance(src, FileSource):
+                # FileSource caches flattened dict already
+                v = src.get(key)
+                if v is not None:
+                    return v
+    return None
+
+def _flatten_obj(obj: Any, prefix: str = "") -> Dict[str, Any]:
+    out: Dict[str, Any] = {}
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            k2 = (prefix + "." + str(k)) if prefix else str(k)
+            out.update(_flatten_obj(v, k2))
+    elif isinstance(obj, (list, tuple)):
+        for i, v in enumerate(obj):
+            k2 = (prefix + "." + str(i)) if prefix else str(i)
+            out.update(_flatten_obj(v, k2))
+    else:
+        out[prefix] = obj
+        if "." in prefix:
+            # also expose leaf as KEY without dots if single-segment? no; keep dotted only
+            pass
+        # also expose top-level KEY without dots when no prefix used:
+        if prefix and "." not in prefix:
+            out[prefix] = obj
+    # Additionally mirror top-level simple keys as UPPERCASE for convenience
+    if prefix and "." not in prefix:
+        out[prefix.upper()] = obj
+    return out
+
+def _strip_quotes(s: str) -> str:
+    if (s.startswith('"') and s.endswith('"')) or (s.startswith("'") and s.endswith("'")):
+        return s[1:-1]
+    return s
+
+def _coerce_type(val: Any, ann: Any) -> Any:
+    if val is None:
+        return None
+    # strings from sources come as str; coerce to basic types
+    try:
+        from typing import get_origin, get_args
+        origin = get_origin(ann) or ann
+        if origin in (int,):
+            return int(val)
+        if origin in (float,):
+            return float(val)
+        if origin in (bool,):
+            s = str(val).strip().lower()
+            if s in ("1","true","yes","y","on"): return True
+            if s in ("0","false","no","n","off"): return False
+            return bool(val)
+    except Exception:
+        pass
+    return val
+
+def _get_type_hints_safe(fn, owner=None):
+    try:
+        import inspect
+        mod = inspect.getmodule(fn)
+        g = getattr(mod, "__dict__", {})
+        l = vars(owner) if owner is not None else None
+        from typing import get_type_hints
+        return get_type_hints(fn, globalns=g, localns=l, include_extras=True)
+    except Exception:
+        return {}
+
+# ---- Public API helpers to be imported by users ----
+
+__all__ = [
+    "config_component", "EnvSource", "FileSource",
+    "Env", "File", "Path", "Value",
+    "ConfigRegistry", "register_field_spec", "is_config_component",
+]
+

pico_ioc/container.py

@@ -1,16 +1,16 @@
-# src/pico_ioc/container.py (Refactorizado)
 from __future__ import annotations
+
 import inspect
-from typing import Any, Dict, get_origin, get_args, Annotated, Sequence, Optional, Callable, Union, Tuple
+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"):
+    def __init__(self, container: PicoContainer):
         self._c = container
 
     def bind(self, key: Any, provider, *, lazy: bool, tags: tuple[str, ...] = ()):
@@ -22,21 +22,17 @@ class Binder:
     def get(self, key: Any):
         return self._c.get(key)
 
-
 class PicoContainer:
-    def __init__(self, providers: Dict[Any, Dict[str, Any]]):
-        self._providers = providers
+    def __init__(self, providers: Dict[Any, Dict[str, Any]] | None = None):
+        self._providers = providers or {}
         self._singletons: Dict[Any, Any] = {}
         self._method_interceptors: tuple[MethodInterceptor, ...] = ()
         self._container_interceptors: tuple[ContainerInterceptor, ...] = ()
         self._active_profiles: tuple[str, ...] = ()
         self._seen_interceptor_types: set[type] = set()
+        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:
@@ -45,9 +41,11 @@ class PicoContainer:
             return
         self._seen_interceptor_types.add(t)
         self._container_interceptors = self._container_interceptors + (it,)
-        
+
+    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:
-        """Returns a binder for this container."""
         return Binder(self)
 
     def bind(self, key: Any, provider, *, lazy: bool, tags: tuple[str, ...] = ()):
@@ -64,6 +62,10 @@ class PicoContainer:
     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")
@@ -72,34 +74,21 @@ class PicoContainer:
             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
 
@@ -132,18 +121,15 @@ class PicoContainer:
     def get_providers(self) -> Dict[Any, Dict]:
         return self._providers.copy()
 
-
 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("_"))
@@ -153,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

pico_ioc/decorators.py

@@ -1,7 +1,6 @@
-# pico_ioc/decorators.py
 from __future__ import annotations
 import functools
-from typing import Any, Iterable, Optional, Callable, Tuple, Literal
+from typing import Any, Iterable, Optional, Callable, Tuple
 
 COMPONENT_FLAG = "_is_component"
 COMPONENT_KEY = "_component_key"
@@ -21,14 +20,12 @@ ON_MISSING_META = "_pico_on_missing"
 PRIMARY_FLAG = "_pico_primary"
 CONDITIONAL_META = "_pico_conditional"
 
-INTERCEPTOR_META = "__pico_interceptor__"
-
+INFRA_META = "__pico_infrastructure__"
 
 def factory_component(cls):
     setattr(cls, FACTORY_FLAG, True)
     return cls
 
-
 def component(cls=None, *, name: Any = None, lazy: bool = False, tags: Iterable[str] = ()):
     def dec(c):
         setattr(c, COMPONENT_FLAG, True)
@@ -38,7 +35,6 @@ def component(cls=None, *, name: Any = None, lazy: bool = False, tags: Iterable[
         return c
     return dec(cls) if cls else dec
 
-
 def provides(key: Any, *, lazy: bool = False, tags: Iterable[str] = ()):
     def dec(fn):
         @functools.wraps(fn)
@@ -50,16 +46,13 @@ def provides(key: Any, *, lazy: bool = False, tags: Iterable[str] = ()):
         return w
     return dec
 
-
 def plugin(cls):
     setattr(cls, PLUGIN_FLAG, True)
     return cls
 
-
 class Qualifier(str):
     __slots__ = ()
 
-
 def qualifier(*qs: Qualifier):
     def dec(cls):
         current: Iterable[Qualifier] = getattr(cls, QUALIFIERS_KEY, ())
@@ -73,23 +66,20 @@ def qualifier(*qs: Qualifier):
         return cls
     return dec
 
-
 def on_missing(selector: object, *, priority: int = 0):
     def dec(obj):
         setattr(obj, ON_MISSING_META, {"selector": selector, "priority": int(priority)})
         return obj
     return dec
 
-
 def primary(obj):
     setattr(obj, PRIMARY_FLAG, True)
     return obj
 
-
 def conditional(
     *,
-    profiles: tuple[str, ...] = (),
-    require_env: tuple[str, ...] = (),
+    profiles: Tuple[str, ...] = (),
+    require_env: Tuple[str, ...] = (),
     predicate: Optional[Callable[[], bool]] = None,
 ):
     def dec(obj):
@@ -101,34 +91,30 @@ def conditional(
         return obj
     return dec
 
-
-def interceptor(
-    _obj=None,
-    *,
-    kind: Literal["method", "container"] = "method",
-    order: int = 0,
+def infrastructure(
+    _cls=None, *, order: int = 0,
     profiles: Tuple[str, ...] = (),
     require_env: Tuple[str, ...] = (),
-    predicate: Callable[[], bool] | None = None,
+    predicate: Optional[Callable[[], bool]] = None,
 ):
-    def dec(obj):
-        setattr(obj, INTERCEPTOR_META, {
-            "kind": kind,
+    def dec(cls):
+        setattr(cls, INFRA_META, {
             "order": int(order),
             "profiles": tuple(profiles),
             "require_env": tuple(require_env),
             "predicate": predicate,
         })
-        return obj
-    return dec if _obj is None else dec(_obj)
+        return cls
+    return dec if _cls is None else dec(_cls)
 
 __all__ = [
-    "component", "factory_component", "provides", "plugin", "qualifier", "Qualifier",
+    "component", "factory_component", "provides", "plugin",
+    "Qualifier", "qualifier",
+    "on_missing", "primary", "conditional", "infrastructure",
     "COMPONENT_FLAG", "COMPONENT_KEY", "COMPONENT_LAZY",
     "FACTORY_FLAG", "PROVIDES_KEY", "PROVIDES_LAZY",
     "PLUGIN_FLAG", "QUALIFIERS_KEY", "COMPONENT_TAGS", "PROVIDES_TAGS",
-    "on_missing", "primary", "conditional",
     "ON_MISSING_META", "PRIMARY_FLAG", "CONDITIONAL_META",
-    "interceptor", "INTERCEPTOR_META",
+    "INFRA_META",
 ]