pico-ioc 1.5.0__py3-none-any.whl → 2.0.1__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,120 +0,0 @@
-from __future__ import annotations
-import functools
-from typing import Any, Iterable, Optional, Callable, Tuple
-
-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"
-
-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)
-        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] = ()):
-    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):
-    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, ())
-        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
-
-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, ...] = (),
-    predicate: Optional[Callable[[], bool]] = None,
-):
-    def dec(obj):
-        setattr(obj, CONDITIONAL_META, {
-            "profiles": tuple(profiles),
-            "require_env": tuple(require_env),
-            "predicate": predicate,
-        })
-        return obj
-    return dec
-
-def infrastructure(
-    _cls=None, *, order: int = 0,
-    profiles: Tuple[str, ...] = (),
-    require_env: Tuple[str, ...] = (),
-    predicate: Optional[Callable[[], bool]] = None,
-):
-    def dec(cls):
-        setattr(cls, INFRA_META, {
-            "order": int(order),
-            "profiles": tuple(profiles),
-            "require_env": tuple(require_env),
-            "predicate": predicate,
-        })
-        return cls
-    return dec if _cls is None else dec(_cls)
-
-__all__ = [
-    "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_META", "PRIMARY_FLAG", "CONDITIONAL_META",
-    "INFRA_META",
-]
-

pico_ioc/infra.py

@@ -1,196 +0,0 @@
-from __future__ import annotations
-import re
-from typing import Any, Callable, Iterable, Optional, Sequence, Tuple
-
-class Select:
-    def __init__(self):
-        self._tags: set[str] = set()
-        self._profiles: set[str] = set()
-        self._class_name_regex: Optional[re.Pattern[str]] = None
-        self._method_name_regex: Optional[re.Pattern[str]] = None
-
-    def has_tag(self, *tags: str) -> "Select":
-        self._tags.update(t for t in tags if t)
-        return self
-
-    def profile_in(self, *profiles: str) -> "Select":
-        self._profiles.update(p for p in profiles if p)
-        return self
-
-    def class_name(self, regex: str) -> "Select":
-        self._class_name_regex = re.compile(regex)
-        return self
-
-    def method_name(self, regex: str) -> "Select":
-        self._method_name_regex = re.compile(regex)
-        return self
-
-    def is_effectively_empty(self) -> bool:
-        return not (self._tags or self._profiles or self._class_name_regex or self._method_name_regex)
-
-    def match_provider(self, key: Any, meta: dict, *, active_profiles: Sequence[str]) -> bool:
-        if self.is_effectively_empty():
-            return False
-        if self._tags:
-            tags = set(meta.get("tags", ()))
-            if not tags.intersection(self._tags):
-                return False
-        if self._profiles:
-            if not set(active_profiles).intersection(self._profiles):
-                return False
-        if self._class_name_regex and isinstance(key, type):
-            if not self._class_name_regex.search(getattr(key, "__name__", "")):
-                return False
-        return True
-
-    def match_method_name(self, method: str) -> bool:
-        if self._method_name_regex is None:
-            return True
-        return bool(self._method_name_regex.search(method))
-
-
-class InfraQuery:
-    def __init__(self, container, profiles: Tuple[str, ...]):
-        self.c = container
-        self.profiles = profiles
-
-    def providers(self, where: Optional[Select] = None, *, limit: Optional[int] = None) -> list[tuple[Any, dict]]:
-        sel = where or Select()
-        items: list[tuple[Any, dict]] = []
-        for k, m in self.c._providers.items():
-            if sel.match_provider(k, m, active_profiles=self.profiles):
-                items.append((k, m))
-                if limit is not None and len(items) >= limit:
-                    break
-        return items
-
-    def components(self, where: Optional[Select] = None, *, limit: Optional[int] = None) -> list[type]:
-        out: list[type] = []
-        for k, _m in self.providers(where=where, limit=limit):
-            if isinstance(k, type):
-                out.append(k)
-        return out
-
-
-class InfraIntercept:
-    def __init__(self, container, profiles: Tuple[str, ...]):
-        self.c = container
-        self.profiles = profiles
-        self._per_method_cap: Optional[int] = None
-
-    def _collect_target_classes(self, where: Select) -> tuple[set[type], set[Any]]:
-        classes: set[type] = set()
-        keys: set[Any] = set()
-        for key, meta in self.c._providers.items():
-            if where.match_provider(key, meta, active_profiles=self.profiles):
-                keys.add(key)
-                if isinstance(key, type):
-                    classes.add(key)
-        return classes, keys
-
-    def _guard_method_interceptor(self, interceptor, where: Select):
-        target_classes, _keys = self._collect_target_classes(where)
-        class_names = {cls.__name__ for cls in target_classes}
-        class Guarded:
-            def invoke(self, ctx, call_next):
-                tgt_cls = type(ctx.instance)
-                ok_class = any(isinstance(ctx.instance, cls) for cls in target_classes) or (getattr(tgt_cls, "__name__", "") in class_names)
-                ok_method = where.match_method_name(ctx.name)
-                if ok_class and ok_method:
-                    return interceptor.invoke(ctx, call_next) if hasattr(interceptor, "invoke") else interceptor(ctx, call_next)
-                return call_next(ctx)
-        return Guarded()
-
-    def _guard_container_interceptor(self, interceptor, where: Select):
-        target_classes, keys = self._collect_target_classes(where)
-        class_names = {cls.__name__ for cls in target_classes}
-        def _ok(key: Any) -> bool:
-            if key in keys:
-                return True
-            if isinstance(key, type) and (key in target_classes or getattr(key, "__name__", "") in class_names):
-                return True
-            return False
-        class GuardedCI:
-            def around_resolve(self, ctx, call_next):
-                if _ok(ctx.key):
-                    return interceptor.around_resolve(ctx, call_next)
-                return call_next(ctx)
-            def around_create(self, ctx, call_next):
-                if _ok(ctx.key):
-                    return interceptor.around_create(ctx, call_next)
-                return call_next(ctx)
-        return GuardedCI()
-
-    def add(self, *, interceptor, where: Select) -> None:
-        sel = where or Select()
-        if sel.is_effectively_empty():
-            raise ValueError("empty selector for interceptor")
-        is_container = all(hasattr(interceptor, m) for m in ("around_resolve", "around_create"))
-        if is_container:
-            guarded = self._guard_container_interceptor(interceptor, sel)
-            self.c.add_container_interceptor(guarded)
-            return
-        guarded = self._guard_method_interceptor(interceptor, sel)
-        self.c.add_method_interceptor(guarded)
-
-    def limit_per_method(self, max_n: int) -> None:
-        self._per_method_cap = int(max_n)
-
-
-class InfraMutate:
-    def __init__(self, container, profiles: Tuple[str, ...]):
-        self.c = container
-        self.profiles = profiles
-
-    def add_tags(self, component_or_key: Any, tags: Iterable[str]) -> None:
-        key = component_or_key
-        if key in self.c._providers:
-            meta = self.c._providers[key]
-            cur = tuple(meta.get("tags", ()))
-            new = tuple(dict.fromkeys(list(cur) + [t for t in tags if t]))
-            meta["tags"] = new
-            self.c._providers[key] = meta
-
-    def set_qualifiers(self, provider_key: Any, qualifiers: dict[str, Any]) -> None:
-        if provider_key in self.c._providers:
-            meta = self.c._providers[provider_key]
-            meta["qualifiers"] = tuple(qualifiers or ())
-            self.c._providers[provider_key] = meta
-
-    def replace_provider(self, *, key: Any, with_factory: Callable[[], object]) -> None:
-        if key in self.c._providers:
-            lazy = bool(self.c._providers[key].get("lazy", False))
-            self.c.bind(key, with_factory, lazy=lazy, tags=self.c._providers[key].get("tags", ()))
-
-    def wrap_provider(self, *, key: Any, around: Callable[[Callable[[], object]], Callable[[], object]]) -> None:
-        if key in self.c._providers:
-            meta = self.c._providers[key]
-            base_factory = meta.get("factory")
-            if callable(base_factory):
-                wrapped = around(base_factory)
-                self.c.bind(key, wrapped, lazy=bool(meta.get("lazy", False)), tags=meta.get("tags", ()))
-
-    def rename_key(self, *, old: Any, new: Any) -> None:
-        if old in self.c._providers and new not in self.c._providers:
-            self.c._providers[new] = self.c._providers.pop(old)
-
-class Infra:
-    def __init__(self, *, container, profiles: Tuple[str, ...]):
-        self._c = container
-        self._profiles = profiles
-        self._query = InfraQuery(container, profiles)
-        self._intercept = InfraIntercept(container, profiles)
-        self._mutate = InfraMutate(container, profiles)
-
-    @property
-    def query(self) -> InfraQuery:
-        return self._query
-
-    @property
-    def intercept(self) -> InfraIntercept:
-        return self._intercept
-
-    @property
-    def mutate(self) -> InfraMutate:
-        return self._mutate
-