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

pico_ioc/config.py

@@ -1,332 +0,0 @@
-# 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/decorators.py

@@ -1,158 +0,0 @@
-# src/pico_ioc/decorators.py
-from __future__ import annotations
-
-import functools
-from typing import Any, Iterable, Optional, Callable, Tuple, Literal
-
-
-# ---- marker attributes (read by scanner/policy) ----
-
-COMPONENT_FLAG = "_is_component"
-COMPONENT_KEY = "_component_key"
-COMPONENT_LAZY = "_component_lazy"
-
-FACTORY_FLAG = "_is_factory_component"
-PROVIDES_KEY = "_provides_name"
-PROVIDES_LAZY = "_pico_lazy"
-
-PLUGIN_FLAG = "_is_pico_plugin"
-QUALIFIERS_KEY = "_pico_qualifiers"
-
-COMPONENT_TAGS = "_pico_tags"
-PROVIDES_TAGS = "_pico_tags"
-
-ON_MISSING_META = "_pico_on_missing"
-PRIMARY_FLAG = "_pico_primary"
-CONDITIONAL_META = "_pico_conditional"
-
-INTERCEPTOR_META = "__pico_interceptor__"
-
-
-# ---- core decorators ----
-
-def factory_component(cls):
-    """Mark a class as a factory component (its methods can @provides)."""
-    setattr(cls, FACTORY_FLAG, True)
-    return cls
-
-
-def component(cls=None, *, name: Any = None, lazy: bool = False, tags: Iterable[str] = ()):
-    """Mark a class as a component. Optional: custom key, lazy instantiation, tags."""
-    def dec(c):
-        setattr(c, COMPONENT_FLAG, True)
-        setattr(c, COMPONENT_KEY, name if name is not None else c)
-        setattr(c, COMPONENT_LAZY, bool(lazy))
-        setattr(c, COMPONENT_TAGS, tuple(tags) if tags else ())
-        return c
-    return dec(cls) if cls else dec
-
-
-def provides(key: Any, *, lazy: bool = False, tags: Iterable[str] = ()):
-    """Declare a factory method that provides a binding for `key`."""
-    def dec(fn):
-        @functools.wraps(fn)
-        def w(*a, **k):
-            return fn(*a, **k)
-        setattr(w, PROVIDES_KEY, key)
-        setattr(w, PROVIDES_LAZY, bool(lazy))
-        setattr(w, PROVIDES_TAGS, tuple(tags) if tags else ())
-        return w
-    return dec
-
-
-def plugin(cls):
-    """Mark a class as a Pico plugin (scanner lifecycle)."""
-    setattr(cls, PLUGIN_FLAG, True)
-    return cls
-
-
-# ---- qualifiers ----
-
-class Qualifier(str):
-    """String qualifier type used with Annotated[T, 'q1', ...]."""
-    __slots__ = ()
-
-
-def qualifier(*qs: Qualifier):
-    """Attach one or more qualifiers to a component class key."""
-    def dec(cls):
-        current: Iterable[Qualifier] = getattr(cls, QUALIFIERS_KEY, ())
-        seen = set(current)
-        merged = list(current)
-        for q in qs:
-            if q not in seen:
-                merged.append(q)
-                seen.add(q)
-        setattr(cls, QUALIFIERS_KEY, tuple(merged))
-        return cls
-    return dec
-
-
-# ---- defaults / selection ----
-
-def on_missing(selector: object, *, priority: int = 0):
-    """Declare this target as a default for `selector` when no binding exists."""
-    def dec(obj):
-        setattr(obj, ON_MISSING_META, {"selector": selector, "priority": int(priority)})
-        return obj
-    return dec
-
-
-def primary(obj):
-    """Hint this candidate should be preferred among equals."""
-    setattr(obj, PRIMARY_FLAG, True)
-    return obj
-
-
-def conditional(
-    *,
-    profiles: Tuple[str, ...] = (),
-    require_env: Tuple[str, ...] = (),
-    predicate: Optional[Callable[[], bool]] = None,
-):
-    """Activate only when profiles/env/predicate conditions pass."""
-    def dec(obj):
-        setattr(obj, CONDITIONAL_META, {
-            "profiles": tuple(profiles),
-            "require_env": tuple(require_env),
-            "predicate": predicate,
-        })
-        return obj
-    return dec
-
-
-# ---- interceptors ----
-
-def interceptor(
-    _obj=None,
-    *,
-    kind: Literal["method", "container"] = "method",
-    order: int = 0,
-    profiles: Tuple[str, ...] = (),
-    require_env: Tuple[str, ...] = (),
-    predicate: Callable[[], bool] | None = None,
-):
-    """Declare an interceptor (method or container) with optional activation metadata."""
-    def dec(obj):
-        setattr(obj, INTERCEPTOR_META, {
-            "kind": kind,
-            "order": int(order),
-            "profiles": tuple(profiles),
-            "require_env": tuple(require_env),
-            "predicate": predicate,
-        })
-        return obj
-    return dec if _obj is None else dec(_obj)
-
-
-__all__ = [
-    "component", "factory_component", "provides", "plugin",
-    "Qualifier", "qualifier",
-    "on_missing", "primary", "conditional", "interceptor",
-    "COMPONENT_FLAG", "COMPONENT_KEY", "COMPONENT_LAZY",
-    "FACTORY_FLAG", "PROVIDES_KEY", "PROVIDES_LAZY",
-    "PLUGIN_FLAG", "QUALIFIERS_KEY", "COMPONENT_TAGS", "PROVIDES_TAGS",
-    "ON_MISSING_META", "PRIMARY_FLAG", "CONDITIONAL_META",
-    "INTERCEPTOR_META",
-]
-

pico_ioc/interceptors.py

@@ -1,56 +0,0 @@
-# src/pico_ioc/interceptors.py
-from __future__ import annotations
-
-import inspect
-from typing import Any, Callable, Protocol, Sequence
-
-
-class Invocation:
-    __slots__ = ("target", "method_name", "call", "args", "kwargs", "is_async")
-
-    def __init__(self, target: object, method_name: str, call: Callable[..., Any],
-                 args: tuple, kwargs: dict):
-        self.target = target
-        self.method_name = method_name
-        self.call = call
-        self.args = args
-        self.kwargs = kwargs
-        self.is_async = inspect.iscoroutinefunction(call)
-
-
-class MethodInterceptor(Protocol):
-    def __call__(self, inv: Invocation, proceed: Callable[[], Any]) -> Any: ...
-
-
-async def _chain_async(interceptors: Sequence[MethodInterceptor], inv: Invocation, i: int = 0):
-    if i >= len(interceptors):
-        return await inv.call(*inv.args, **inv.kwargs)
-    cur = interceptors[i]
-
-    async def next_step():
-        return await _chain_async(interceptors, inv, i + 1)
-
-    res = cur(inv, next_step)
-    return await res if inspect.isawaitable(res) else res
-
-
-def _chain_sync(interceptors: Sequence[MethodInterceptor], inv: Invocation, i: int = 0):
-    if i >= len(interceptors):
-        return inv.call(*inv.args, **inv.kwargs)
-    cur = interceptors[i]
-    return cur(inv, lambda: _chain_sync(interceptors, inv, i + 1))
-
-
-def dispatch(interceptors: Sequence[MethodInterceptor], inv: Invocation):
-    """Dispatch invocation through a chain of interceptors."""
-    if inv.is_async:
-        return _chain_async(interceptors, inv, 0)  # coroutine
-    return _chain_sync(interceptors, inv, 0)       # value
-
-
-class ContainerInterceptor(Protocol):
-    def on_resolve(self, key: Any, annotation: Any, qualifiers: tuple[str, ...] | tuple()) -> None: ...
-    def on_before_create(self, key: Any) -> None: ...
-    def on_after_create(self, key: Any, instance: Any) -> Any: ...
-    def on_exception(self, key: Any, exc: BaseException) -> None: ...
-

pico_ioc/plugins.py

@@ -1,28 +0,0 @@
-# pico_ioc/plugins.py
-from typing import Protocol, Any, Tuple
-from .container import Binder, PicoContainer
-import logging
-
-class PicoPlugin(Protocol):
-    def before_scan(self, package: Any, binder: Binder) -> None: ...
-    def visit_class(self, module: Any, cls: type, binder: Binder) -> None: ...
-    def after_scan(self, package: Any, binder: Binder) -> None: ...
-    def after_bind(self, container: PicoContainer, binder: Binder) -> None: ...
-    def before_eager(self, container: PicoContainer, binder: Binder) -> None: ...
-    def after_ready(self, container: PicoContainer, binder: Binder) -> None: ...
-
-def run_plugin_hook(
-    plugins: Tuple[PicoPlugin, ...],
-    hook_name: str,
-    *args,
-    **kwargs,
-) -> None:
-    """Run a lifecycle hook across all plugins, logging (but not raising) exceptions."""
-    for pl in plugins:
-        try:
-            fn = getattr(pl, hook_name, None)
-            if fn:
-                fn(*args, **kwargs)
-        except Exception:
-            logging.exception("Plugin %s failed", hook_name)
-