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

pico_ioc/builder.py

@@ -0,0 +1,294 @@
+# 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
+
+from .interceptors import MethodInterceptor, ContainerInterceptor
+from .container import PicoContainer, _is_compatible
+from .policy import apply_policy, _conditional_active
+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] = {}
+        self._profiles: Optional[List[str]] = None
+        self._plugins: Tuple[PicoPlugin, ...] = ()
+        self._include_tags: Optional[set[str]] = None
+        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
+
+    # -------- 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 or ()
+        return self
+
+    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":
+        self._scan_plan.append((package, exclude, self._plugins))
+        return self
+
+    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":
+        self._include_tags = include
+        self._exclude_tags = exclude
+        return self
+
+    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)
+
+        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)
+                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,
+        )
+
+        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)
+
+        if self._eager:
+            container.eager_instantiate_all()
+        logging.info("Container configured and ready.")
+        return container
+
+
+# ---------------- 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]
+    if callable(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
+
+    def _tag_ok(meta: dict) -> bool:
+        tags = set(meta.get("tags", ()))
+        if include_tags and not tags.intersection(include_tags):
+            return False
+        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)
+    stack = list(roots or ())
+
+    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
+            if cls is not None and _is_compatible(cls, base_t):
+                if prov_key not in allowed:
+                    allowed.add(prov_key)
+                    stack.append(prov_key)
+
+    while stack:
+        k = stack.pop()
+        allowed.add(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
+
+        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
+            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 isinstance(inner, type):
+                    if inner not in allowed:
+                        stack.append(inner)
+                continue
+            if isinstance(ann, type) and ann not in allowed:
+                stack.append(ann)
+            elif container.has(pname) and pname not in allowed:
+                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:
+        profs = tuple(meta.get("profiles", ())) or ()
+        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
+        pred = meta.get("predicate", None)
+        if callable(pred):
+            try:
+                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}")
+            continue
+
+        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)
+        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)
+            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)  # type: ignore[arg-type]
+            activated_container_names.append(_qn)
+        else:
+            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 "-",
+        )
+    if skipped_debug:
+        logging.debug("Skipped interceptors: %s", ", ".join(skipped_debug))
+

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",
+]
+