pico-ioc 2.0.5__py3-none-any.whl → 2.1.1__py3-none-any.whl

pico_ioc/component_scanner.py

@@ -0,0 +1,166 @@
+import inspect
+import os
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union, Set
+from .constants import PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
+from .factory import ProviderMetadata, DeferredProvider
+from .decorators import get_return_type
+from .config_registrar import ConfigurationManager
+from .analysis import analyze_callable_dependencies, DependencyRequest
+
+KeyT = Union[str, type]
+Provider = Callable[[], Any]
+
+class ComponentScanner:
+    def __init__(self, profiles: Set[str], environ: Dict[str, str], config_manager: ConfigurationManager):
+        self._profiles = profiles
+        self._environ = environ
+        self._config_manager = config_manager
+        self._candidates: Dict[KeyT, List[Tuple[bool, Provider, ProviderMetadata]]] = {}
+        self._on_missing: List[Tuple[int, KeyT, type]] = []
+        self._deferred: List[DeferredProvider] = []
+        self._provides_functions: Dict[KeyT, Callable[..., Any]] = {}
+
+    def get_scan_results(self) -> Tuple[Dict[KeyT, List[Tuple[bool, Provider, ProviderMetadata]]], List[Tuple[int, KeyT, type]], List[DeferredProvider], Dict[KeyT, Callable[..., Any]]]:
+        return self._candidates, self._on_missing, self._deferred, self._provides_functions
+
+    def _queue(self, key: KeyT, provider: Provider, md: ProviderMetadata) -> None:
+        lst = self._candidates.setdefault(key, [])
+        lst.append((md.primary, provider, md))
+        if isinstance(provider, DeferredProvider):
+            self._deferred.append(provider)
+
+    def _enabled_by_condition(self, obj: Any) -> bool:
+        meta = getattr(obj, PICO_META, {})
+        c = meta.get("conditional", None)
+        if not c:
+            return True
+
+        p = set(c.get("profiles") or ())
+        if p and not (p & self._profiles):
+            return False
+
+        req = c.get("require_env") or ()
+        for k in req:
+            if k not in self._environ or not self._environ.get(k):
+                return False
+
+        pred = c.get("predicate")
+        if pred is None:
+            return True
+
+        try:
+            ok = bool(pred())
+        except Exception:
+            return False
+        if not ok:
+            return False
+
+        return True
+
+    def _register_component_class(self, cls: type) -> None:
+        if not self._enabled_by_condition(cls):
+            return
+        key = getattr(cls, PICO_KEY, cls)
+        qset = set(str(q) for q in getattr(cls, PICO_META, {}).get("qualifier", ()))
+        sc = getattr(cls, PICO_META, {}).get("scope", "singleton")
+        deps = analyze_callable_dependencies(cls.__init__)
+        provider = DeferredProvider(lambda pico, loc, c=cls, d=deps: pico.build_class(c, loc, d))
+        md = ProviderMetadata(key=key, provided_type=cls, concrete_class=cls, factory_class=None, factory_method=None, qualifiers=qset, primary=bool(getattr(cls, PICO_META, {}).get("primary")), lazy=bool(getattr(cls, PICO_META, {}).get("lazy", False)), infra=getattr(cls, PICO_INFRA, None), pico_name=getattr(cls, PICO_NAME, None), scope=sc, dependencies=deps)
+        self._queue(key, provider, md)
+
+    def _register_factory_class(self, cls: type) -> None:
+        if not self._enabled_by_condition(cls):
+            return
+
+        factory_deps: Optional[Tuple[DependencyRequest, ...]] = None
+        has_instance_provides = False
+        for name in dir(cls):
+                 try:
+                     raw = inspect.getattr_static(cls, name)
+                     if inspect.isfunction(raw) and getattr(raw, PICO_INFRA, None) == "provides":
+                         has_instance_provides = True
+                         break
+                 except Exception:
+                     continue
+
+        if has_instance_provides:
+            factory_deps = analyze_callable_dependencies(cls.__init__)
+
+
+        for name in dir(cls):
+            try:
+                raw = inspect.getattr_static(cls, name)
+            except Exception:
+                continue
+
+            fn = None
+            kind = None
+            if isinstance(raw, staticmethod):
+                fn = raw.__func__
+                kind = "static"
+            elif isinstance(raw, classmethod):
+                fn = raw.__func__
+                kind = "class"
+            elif inspect.isfunction(raw):
+                fn = raw
+                kind = "instance"
+            else:
+                continue
+
+            if getattr(fn, PICO_INFRA, None) != "provides":
+                continue
+            if not self._enabled_by_condition(fn):
+                continue
+
+            k = getattr(fn, PICO_KEY)
+            deps = analyze_callable_dependencies(fn)
+
+            if kind == "instance":
+                if factory_deps is None: factory_deps = analyze_callable_dependencies(cls.__init__)
+                provider = DeferredProvider(lambda pico, loc, fc=cls, mn=name, df=factory_deps, dm=deps: pico.build_method(getattr(pico.build_class(fc, loc, df), mn), loc, dm))
+            else:
+                provider = DeferredProvider(lambda pico, loc, f=fn, d=deps: pico.build_method(f, loc, d))
+
+            rt = get_return_type(fn)
+            qset = set(str(q) for q in getattr(fn, PICO_META, {}).get("qualifier", ()))
+            sc = getattr(fn, PICO_META, {}).get("scope", getattr(cls, PICO_META, {}).get("scope", "singleton"))
+            md = ProviderMetadata(key=k, provided_type=rt if isinstance(rt, type) else (k if isinstance(k, type) else None), concrete_class=None, factory_class=cls, factory_method=name, qualifiers=qset, primary=bool(getattr(fn, PICO_META, {}).get("primary")), lazy=bool(getattr(fn, PICO_META, {}).get("lazy", False)), infra=getattr(cls, PICO_INFRA, None), pico_name=getattr(fn, PICO_NAME, None), scope=sc, dependencies=deps)
+            self._queue(k, provider, md)
+
+    def _register_provides_function(self, fn: Callable[..., Any]) -> None:
+        if not self._enabled_by_condition(fn):
+            return
+        k = getattr(fn, PICO_KEY)
+        deps = analyze_callable_dependencies(fn)
+        provider = DeferredProvider(lambda pico, loc, f=fn, d=deps: pico.build_method(f, loc, d))
+        rt = get_return_type(fn)
+        qset = set(str(q) for q in getattr(fn, PICO_META, {}).get("qualifier", ()))
+        sc = getattr(fn, PICO_META, {}).get("scope", "singleton")
+        md = ProviderMetadata(key=k, provided_type=rt if isinstance(rt, type) else (k if isinstance(k, type) else None), concrete_class=None, factory_class=None, factory_method=getattr(fn, "__name__", None), qualifiers=qset, primary=bool(getattr(fn, PICO_META, {}).get("primary")), lazy=bool(getattr(fn, PICO_META, {}).get("lazy", False)), infra="provides", pico_name=getattr(fn, PICO_NAME, None), scope=sc, dependencies=deps)
+        self._queue(k, provider, md)
+        self._provides_functions[k] = fn
+
+    def scan_module(self, module: Any) -> None:
+        for _, obj in inspect.getmembers(module):
+            if inspect.isclass(obj):
+                meta = getattr(obj, PICO_META, {})
+                if "on_missing" in meta:
+                    sel = meta["on_missing"]["selector"]
+                    pr = int(meta["on_missing"].get("priority", 0))
+                    self._on_missing.append((pr, sel, obj))
+                    continue
+
+                infra = getattr(obj, PICO_INFRA, None)
+                if infra == "component":
+                    self._register_component_class(obj)
+                elif infra == "factory":
+                    self._register_factory_class(obj)
+                elif infra == "configured":
+                    enabled = self._enabled_by_condition(obj)
+                    reg_data = self._config_manager.register_configured_class(obj, enabled)
+                    if reg_data:
+                        self._queue(reg_data[0], reg_data[1], reg_data[2])
+
+        for _, fn in inspect.getmembers(module, predicate=inspect.isfunction):
+            if getattr(fn, PICO_INFRA, None) == "provides":
+                self._register_provides_function(fn)

pico_ioc/config_builder.py

@@ -0,0 +1,87 @@
+import os
+import json
+from dataclasses import dataclass
+from typing import Any, Optional, Protocol, Mapping, List, Tuple, Dict, Union
+
+from .config_runtime import TreeSource, DictSource, JsonTreeSource, YamlTreeSource, Value
+from .exceptions import ConfigurationError
+
+class ConfigSource(Protocol):
+    pass
+
+class EnvSource(ConfigSource):
+    def __init__(self, prefix: str = "") -> None:
+        self.prefix = prefix
+    def get(self, key: str) -> Optional[str]:
+        return os.environ.get(self.prefix + key)
+
+class FileSource(ConfigSource):
+    def __init__(self, path: str, prefix: str = "") -> None:
+        self.prefix = prefix
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                self._data = json.load(f)
+        except Exception:
+            self._data = {}
+    def get(self, key: str) -> Optional[str]:
+        k = self.prefix + key
+        v = self._data
+        for part in k.split("__"):
+            if isinstance(v, dict) and part in v:
+                v = v[part]
+            else:
+                return None
+        if isinstance(v, (str, int, float, bool)):
+            return str(v)
+        return None
+
+class FlatDictSource(ConfigSource):
+    def __init__(self, data: Mapping[str, Any], prefix: str = "", case_sensitive: bool = True):
+        base = dict(data)
+        if case_sensitive:
+            self._data = {str(k): v for k, v in base.items()}
+            self._prefix = prefix
+        else:
+            self._data = {str(k).upper(): v for k, v in base.items()}
+            self._prefix = prefix.upper()
+        self._case_sensitive = case_sensitive
+    def get(self, key: str) -> Optional[str]:
+        if not key:
+            return None
+        k = f"{self._prefix}{key}" if self._prefix else key
+        if not self._case_sensitive:
+            k = k.upper()
+        v = self._data.get(k)
+        if v is None:
+            return None
+        if isinstance(v, (str, int, float, bool)):
+            return str(v)
+        return None
+
+@dataclass(frozen=True)
+class ContextConfig:
+    flat_sources: Tuple[Union[EnvSource, FileSource, FlatDictSource], ...]
+    tree_sources: Tuple[TreeSource, ...]
+    overrides: Dict[str, Any]
+
+def configuration(
+    *sources: Any,
+    overrides: Optional[Dict[str, Any]] = None
+) -> ContextConfig:
+    
+    flat: List[Union[EnvSource, FileSource, FlatDictSource]] = []
+    tree: List[TreeSource] = []
+
+    for src in sources:
+        if isinstance(src, (EnvSource, FileSource, FlatDictSource)):
+            flat.append(src)
+        elif isinstance(src, TreeSource):
+            tree.append(src)
+        else:
+            raise ConfigurationError(f"Unknown configuration source type: {type(src)}")
+            
+    return ContextConfig(
+        flat_sources=tuple(flat),
+        tree_sources=tuple(tree),
+        overrides=dict(overrides or {})
+    )

pico_ioc/config_registrar.py

@@ -0,0 +1,236 @@
+import inspect
+from dataclasses import is_dataclass, fields, MISSING
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union, get_args, get_origin, Annotated
+from .constants import PICO_INFRA, PICO_NAME, PICO_META
+from .exceptions import ConfigurationError
+from .factory import ProviderMetadata, DeferredProvider
+from .config_builder import ContextConfig, ConfigSource, FlatDictSource, Value
+from .config_runtime import ConfigResolver, TypeAdapterRegistry, ObjectGraphBuilder, TreeSource
+from .analysis import analyze_callable_dependencies, DependencyRequest
+
+KeyT = Union[str, type]
+Provider = Callable[[], Any]
+
+def _truthy(s: str) -> bool:
+    return s.strip().lower() in {"1", "true", "yes", "on", "y", "t"}
+
+def _coerce(val: Optional[str], t: type) -> Any:
+    if val is None:
+        return None
+    if t is str:
+        return val
+    if t is int:
+        return int(val)
+    if t is float:
+        return float(val)
+    if t is bool:
+        return _truthy(val)
+    org = get_origin(t)
+    if org is Union:
+        args = [a for a in get_args(t) if a is not type(None)]
+        if not args:
+            return None
+        return _coerce(val, args[0])
+    return val
+
+def _upper_key(name: str) -> str:
+    return name.upper()
+
+def _lookup(sources: Tuple[ConfigSource, ...], key: str) -> Optional[str]:
+    for src in sources:
+        v = src.get(key)
+        if v is not None:
+            return v
+    return None
+
+class ConfigurationManager:
+    def __init__(self, config: Optional[ContextConfig]) -> None:
+        cfg = config or ContextConfig(flat_sources=(), tree_sources=(), overrides={})
+        
+        self._flat_config = cfg.flat_sources
+        self._overrides = cfg.overrides
+        
+        self._resolver = ConfigResolver(cfg.tree_sources)
+        self._adapters = TypeAdapterRegistry()
+        self._graph = ObjectGraphBuilder(self._resolver, self._adapters)
+
+    def _lookup_flat(self, key: str) -> Optional[str]:
+        if key in self._overrides:
+            return str(self._overrides[key])
+        for src in self._flat_config:
+            v = src.get(key)
+            if v is not None:
+                return v
+        return None
+
+    def _build_flat_instance(self, cls: type, prefix: Optional[str]) -> Any:
+        if not is_dataclass(cls):
+            raise ConfigurationError(f"Configuration class {getattr(cls, '__name__', str(cls))} must be a dataclass")
+        values: Dict[str, Any] = {}
+        for f in fields(cls):
+            field_type = f.type
+            value_override = None
+            
+            if get_origin(field_type) is Annotated:
+                args = get_args(field_type)
+                field_type = args[0] if args else Any
+                metas = args[1:] if len(args) > 1 else ()
+                for m in metas:
+                    if isinstance(m, Value):
+                        value_override = m.value
+                        break
+            
+            if value_override is not None:
+                values[f.name] = value_override
+                continue
+            
+            base_key = _upper_key(f.name)
+            keys_to_try = []
+            if prefix:
+                keys_to_try.append(prefix + base_key)
+            keys_to_try.append(base_key)
+            
+            raw = None
+            for k in keys_to_try:
+                raw = self._lookup_flat(k)
+                if raw is not None:
+                    break
+                    
+            if raw is None:
+                if f.default is not MISSING or f.default_factory is not MISSING:
+                    continue
+                raise ConfigurationError(f"Missing configuration key: {(prefix or '') + base_key}")
+            values[f.name] = _coerce(raw, field_type if isinstance(field_type, type) or get_origin(field_type) else str)
+        return cls(**values)
+    
+    def _auto_detect_mapping(self, target_type: type) -> str:
+        if not is_dataclass(target_type):
+            return "tree"
+        
+        primitives = (str, int, float, bool)
+        for f in fields(target_type):
+            t = f.type
+            
+            if get_origin(t) is Annotated:
+                args = get_args(t)
+                t = args[0] if args else Any
+
+            origin = get_origin(t)
+            
+            if origin in (list, List, dict, Dict, Union):
+                return "tree"
+            if isinstance(t, type) and is_dataclass(t):
+                return "tree"
+
+            base_type = t
+            is_optional = origin is Union and type(None) in get_args(t)
+            if is_optional:
+                real_args = [a for a in get_args(t) if a is not type(None)]
+                if real_args:
+                    base_type = real_args[0]
+                else:
+                    continue
+            
+            if isinstance(base_type, type) and base_type not in primitives:
+                return "tree"
+                
+        return "flat"
+
+    def register_configured_class(self, cls: type, enabled: bool) -> Optional[Tuple[KeyT, Provider, ProviderMetadata]]:
+        if not enabled:
+            return None
+        
+        meta = getattr(cls, PICO_META, {})
+        cfg = meta.get("configured", None)
+        if not cfg:
+            return None
+            
+        target = cfg.get("target")
+        prefix = cfg.get("prefix")
+        mapping = cfg.get("mapping", "auto")
+        
+        if target == "self":
+            target = cls
+        
+        if not isinstance(target, type):
+            return None
+            
+        if mapping == "auto":
+            mapping = self._auto_detect_mapping(target)
+            
+        graph_builder = self._graph
+        qset = set(str(q) for q in meta.get("qualifier", ()))
+        sc = meta.get("scope", "singleton")
+        
+        if mapping == "tree":
+            provider = DeferredProvider(lambda pico, loc, t=target, p=prefix, g=graph_builder: g.build_from_prefix(t, p))
+            deps = ()
+            if not is_dataclass(target) and hasattr(target, "__init__"):
+                deps = analyze_callable_dependencies(target.__init__)
+            md = ProviderMetadata(
+                key=target,
+                provided_type=target,
+                concrete_class=None,
+                factory_class=None,
+                factory_method=None,
+                qualifiers=qset,
+                primary=True,
+                lazy=bool(meta.get("lazy", False)),
+                infra="configured",
+                pico_name=prefix,
+                scope=sc,
+                dependencies=deps
+            )
+            return (target, provider, md)
+            
+        elif mapping == "flat":
+            if not is_dataclass(target):
+                raise ConfigurationError(f"Target class {target.__name__} for flat mapping must be a dataclass")
+            
+            provider = DeferredProvider(lambda pico, loc, c=target, p=prefix: self._build_flat_instance(c, p))
+            md = ProviderMetadata(
+                key=target,
+                provided_type=target,
+                concrete_class=target,
+                factory_class=None,
+                factory_method=None,
+                qualifiers=qset,
+                primary=True,
+                lazy=bool(meta.get("lazy", False)),
+                infra="configured",
+                pico_name=prefix,
+                scope=sc,
+                dependencies=()
+            )
+            return (target, provider, md)
+            
+        return None
+
+    def prefix_exists(self, md: ProviderMetadata) -> bool:
+        if md.infra != "configured":
+            return False
+            
+        target_type = md.provided_type or md.concrete_class
+        if not isinstance(target_type, type):
+            return False
+            
+        meta = getattr(target_type, PICO_META, {})
+        cfg = meta.get("configured", {})
+        mapping = cfg.get("mapping", "auto")
+        
+        if mapping == "auto":
+            mapping = self._auto_detect_mapping(target_type)
+            
+        if mapping == "tree":
+            try:
+                _ = self._resolver.subtree(md.pico_name)
+                return True
+            except Exception:
+                return False
+        else:
+            if not is_dataclass(target_type):
+                return False
+            prefix = md.pico_name or ""
+            keys = [_upper_key(f.name) for f in fields(target_type)]
+            return any(self._lookup_flat(prefix + k) is not None for k in keys)
+

pico_ioc/config_runtime.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/config_runtime.py
 import json
 import os
 import re
@@ -9,6 +8,10 @@ from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple, Union, g
 from .exceptions import ConfigurationError
 from .constants import PICO_META
 
+class Value:
+    def __init__(self, value: Any):
+        self.value = value
+
 class Discriminator:
     def __init__(self, name: str):
         self.name = name
@@ -153,18 +156,23 @@ class ObjectGraphBuilder:
     def _build(self, node: Any, t: Any, path: Tuple[str, ...]) -> Any:
         if t is Any or t is object:
             return node
+        
         adapter = self._registry.get(t) if isinstance(t, type) else None
         if adapter:
             return adapter(node)
+            
         org = get_origin(t)
+        
         if org is Annotated:
-            base, meta = self._split_annotated(t)
-            return self._build_discriminated(node, base, meta, path)
+            base, metas = self._split_annotated(t)
+            return self._build_discriminated(node, base, metas, path)
+            
         if org in (list, List):
             elem_t = get_args(t)[0] if get_args(t) else Any
             if not isinstance(node, list):
                 raise ConfigurationError(f"Expected list at {'.'.join(path)}")
             return [self._build(x, elem_t, path + (str(i),)) for i, x in enumerate(node)]
+            
         if org in (dict, Dict, Mapping):
             args = get_args(t)
             kt = args[0] if args else str
@@ -174,6 +182,7 @@ class ObjectGraphBuilder:
             if not isinstance(node, dict):
                 raise ConfigurationError(f"Expected dict at {'.'.join(path)}")
             return {k: self._build(v, vt, path + (k,)) for k, v in node.items()}
+            
         if org is Union:
             args = [a for a in get_args(t)]
             if not isinstance(node, dict):
@@ -183,6 +192,7 @@ class ObjectGraphBuilder:
                     except Exception:
                         continue
                 raise ConfigurationError(f"No union match at {'.'.join(path)}")
+            
             if "$type" in node:
                 tn = str(node["$type"])
                 for cand in args:
@@ -190,12 +200,14 @@ class ObjectGraphBuilder:
                         cleaned = {k: v for k, v in node.items() if k != "$type"}
                         return self._build(cleaned, cand, path)
                 raise ConfigurationError(f"Discriminator $type did not match at {'.'.join(path)}")
+                
             for cand in args:
                 try:
                     return self._build(node, cand, path)
                 except Exception:
                     continue
             raise ConfigurationError(f"No union match at {'.'.join(path)}")
+            
         if isinstance(t, type) and issubclass(t, Enum):
             if isinstance(node, str):
                 try:
@@ -205,6 +217,7 @@ class ObjectGraphBuilder:
                         if str(e.value) == node:
                             return e
             raise ConfigurationError(f"Invalid enum at {'.'.join(path)}")
+            
         if isinstance(t, type) and is_dataclass(t):
             if not isinstance(node, dict):
                 raise ConfigurationError(f"Expected object at {'.'.join(path)}")
@@ -219,6 +232,7 @@ class ObjectGraphBuilder:
                 else:
                     continue
             return t(**vals)
+            
         if isinstance(t, type):
             if t in (str, int, float, bool):
                 return self._coerce_prim(node, t, path)
@@ -234,27 +248,55 @@ class ObjectGraphBuilder:
                     if name in node:
                         kwargs[name] = self._build(node[name], p.annotation if p.annotation is not inspect._empty else Any, path + (name,))
                 return t(**kwargs)
+                
         return node
+        
     def _split_annotated(self, t: Any) -> Tuple[Any, Tuple[Any, ...]]:
         args = get_args(t)
         base = args[0] if args else Any
         metas = tuple(args[1:]) if len(args) > 1 else ()
         return base, metas
+        
     def _build_discriminated(self, node: Any, base: Any, metas: Tuple[Any, ...], path: Tuple[str, ...]) -> Any:
         disc_name = None
+        disc_value = None
+        has_value = False
+
         for m in metas:
             if isinstance(m, Discriminator):
                 disc_name = m.name
-                break
-        if disc_name and isinstance(node, dict) and disc_name in node:
-            if get_origin(base) is Union:
-                tn = str(node[disc_name])
-                for cand in get_args(base):
-                    if isinstance(cand, type) and getattr(cand, "__name__", "") == tn:
-                        cleaned = {k: v for k, v in node.items() if k != disc_name}
-                        return self._build(cleaned, cand, path)
-                raise ConfigurationError(f"Discriminator {disc_name} did not match at {'.'.join(path)}")
+            if isinstance(m, Value):
+                disc_value = m.value
+                has_value = True
+
+        tn: Optional[str] = None
+
+        if disc_name and has_value:
+            tn = str(disc_value)
+        elif disc_name and isinstance(node, dict) and disc_name in node:
+            tn = str(node[disc_name])
+        
+        if tn is not None and get_origin(base) is Union:
+            for cand in get_args(base):
+                if isinstance(cand, type) and getattr(cand, "__name__", "") == tn:
+                    
+                    cleaned_node = {k: v for k, v in node.items() if k != disc_name}
+                    
+                    if has_value:
+                        cleaned_node[disc_name] = tn
+                    
+                    return self._build(cleaned_node, cand, path)
+            
+            raise ConfigurationError(
+                f"Discriminator value '{tn}' for field '{disc_name}' "
+                f"did not match any type in Union {base} at {'.'.join(path)}"
+            )
+
+        if has_value and not disc_name:
+             return disc_value
+             
         return self._build(node, base, path)
+        
     def _coerce_prim(self, node: Any, t: type, path: Tuple[str, ...]) -> Any:
         if t is str:
             if isinstance(node, str):
@@ -286,4 +328,3 @@ class ObjectGraphBuilder:
                     return False
             raise ConfigurationError(f"Expected bool at {'.'.join(path)}")
         return node
-