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

pico_ioc/api.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/api.py
 import os
 import json
 import inspect
@@ -12,7 +11,6 @@ from .constants import LOGGER, PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
 from .exceptions import (
     ProviderNotFoundError,
     CircularDependencyError,
-    ComponentCreationError,
     ScopeError,
     ConfigurationError,
     SerializationError,
@@ -63,74 +61,120 @@ def _meta_get(obj: Any) -> Dict[str, Any]:
         setattr(obj, PICO_META, m)
     return m
 
-def component(cls=None, *, name: Any = None):
+def component(
+    cls=None,
+    *,
+    name: Any = None,
+    qualifiers: Iterable[str] = (),
+    scope: str = "singleton",
+    primary: bool = False,
+    lazy: bool = False,
+    conditional_profiles: Iterable[str] = (),
+    conditional_require_env: Iterable[str] = (),
+    conditional_predicate: Optional[Callable[[], bool]] = None,
+    on_missing_selector: Optional[object] = None,
+    on_missing_priority: int = 0,
+):
     def dec(c):
         setattr(c, PICO_INFRA, "component")
         setattr(c, PICO_NAME, name if name is not None else getattr(c, "__name__", str(c)))
         setattr(c, PICO_KEY, name if name is not None else c)
-        _meta_get(c)
+        m = _meta_get(c)
+        m["qualifier"] = tuple(str(q) for q in qualifiers or ())
+        m["scope"] = scope
+        if primary:
+            m["primary"] = True
+        if lazy:
+            m["lazy"] = True
+        if conditional_profiles or conditional_require_env or conditional_predicate is not None:
+            m["conditional"] = {
+                "profiles": tuple(p for p in conditional_profiles or ()),
+                "require_env": tuple(e for e in conditional_require_env or ()),
+                "predicate": conditional_predicate,
+            }
+        if on_missing_selector is not None:
+            m["on_missing"] = {"selector": on_missing_selector, "priority": int(on_missing_priority)}
         return c
     return dec(cls) if cls else dec
 
-def factory(cls):
-    setattr(cls, PICO_INFRA, "factory")
-    setattr(cls, PICO_NAME, getattr(cls, "__name__", str(cls)))
-    _meta_get(cls)
-    return cls
+def factory(
+    cls=None,
+    *,
+    name: Any = None,
+    qualifiers: Iterable[str] = (),
+    scope: str = "singleton",
+    primary: bool = False,
+    lazy: bool = False,
+    conditional_profiles: Iterable[str] = (),
+    conditional_require_env: Iterable[str] = (),
+    conditional_predicate: Optional[Callable[[], bool]] = None,
+    on_missing_selector: Optional[object] = None,
+    on_missing_priority: int = 0,
+):
+    def dec(c):
+        setattr(c, PICO_INFRA, "factory")
+        setattr(c, PICO_NAME, name if name is not None else getattr(c, "__name__", str(c)))
+        m = _meta_get(c)
+        m["qualifier"] = tuple(str(q) for q in qualifiers or ())
+        m["scope"] = scope
+        if primary:
+            m["primary"] = True
+        if lazy:
+            m["lazy"] = True
+        if conditional_profiles or conditional_require_env or conditional_predicate is not None:
+            m["conditional"] = {
+                "profiles": tuple(p for p in conditional_profiles or ()),
+                "require_env": tuple(e for e in conditional_require_env or ()),
+                "predicate": conditional_predicate,
+            }
+        if on_missing_selector is not None:
+            m["on_missing"] = {"selector": on_missing_selector, "priority": int(on_missing_priority)}
+        return c
+    return dec(cls) if cls else dec
 
-def provides(key: Any):
+def provides(
+    key: Any,
+    *,
+    name: Any = None,
+    qualifiers: Iterable[str] = (),
+    scope: str = "singleton",
+    primary: bool = False,
+    lazy: bool = False,
+    conditional_profiles: Iterable[str] = (),
+    conditional_require_env: Iterable[str] = (),
+    conditional_predicate: Optional[Callable[[], bool]] = None,
+    on_missing_selector: Optional[object] = None,
+    on_missing_priority: int = 0,
+):
     def dec(fn):
-        @functools.wraps(fn)
+        target = fn.__func__ if isinstance(fn, (staticmethod, classmethod)) else fn
+        @functools.wraps(target)
         def w(*a, **k):
-            return fn(*a, **k)
+            return target(*a, **k)
         setattr(w, PICO_INFRA, "provides")
-        setattr(w, PICO_NAME, key)
+        setattr(w, PICO_NAME, name if name is not None else key)
         setattr(w, PICO_KEY, key)
-        _meta_get(w)
+        m = _meta_get(w)
+        m["qualifier"] = tuple(str(q) for q in qualifiers or ())
+        m["scope"] = scope
+        if primary:
+            m["primary"] = True
+        if lazy:
+            m["lazy"] = True
+        if conditional_profiles or conditional_require_env or conditional_predicate is not None:
+            m["conditional"] = {
+                "profiles": tuple(p for p in conditional_profiles or ()),
+                "require_env": tuple(e for e in conditional_require_env or ()),
+                "predicate": conditional_predicate,
+            }
+        if on_missing_selector is not None:
+            m["on_missing"] = {"selector": on_missing_selector, "priority": int(on_missing_priority)}
         return w
     return dec
 
 class Qualifier(str):
     __slots__ = ()
 
-def qualifier(*qs: Qualifier):
-    def dec(cls):
-        m = _meta_get(cls)
-        cur = tuple(m.get("qualifier", ()))
-        seen = set(cur)
-        merged = list(cur)
-        for q in qs:
-            if q not in seen:
-                merged.append(q)
-                seen.add(q)
-        m["qualifier"] = tuple(merged)
-        return cls
-    return dec
-
-def on_missing(selector: object, *, priority: int = 0):
-    def dec(obj):
-        m = _meta_get(obj)
-        m["on_missing"] = {"selector": selector, "priority": int(priority)}
-        return obj
-    return dec
-
-def primary(obj):
-    m = _meta_get(obj)
-    m["primary"] = True
-    return obj
-
-def conditional(*, profiles: Tuple[str, ...] = (), require_env: Tuple[str, ...] = (), predicate: Optional[Callable[[], bool]] = None):
-    def dec(obj):
-        m = _meta_get(obj)
-        m["conditional"] = {"profiles": tuple(profiles), "require_env": tuple(require_env), "predicate": predicate}
-        return obj
-    return dec
-
-def lazy(obj):
-    m = _meta_get(obj)
-    m["lazy"] = True
-    return obj
-
 def configuration(cls=None, *, prefix: Optional[str] = None):
     def dec(c):
         setattr(c, PICO_INFRA, "configuration")
@@ -150,13 +194,6 @@ def cleanup(fn):
     m["cleanup"] = True
     return fn
 
-def scope(name: str):
-    def dec(obj):
-        m = _meta_get(obj)
-        m["scope"] = name
-        return obj
-    return dec
-
 def configured(target: Any, *, prefix: Optional[str] = None):
     def dec(cls):
         setattr(cls, PICO_INFRA, "configured")
@@ -278,27 +315,82 @@ def _collect_by_type(locator: ComponentLocator, t: type, q: Optional[str]):
             out.append(k)
     return out
 
-def _resolve_args(callable_obj: Callable[..., Any], pico: "PicoContainer") -> Dict[str, Any]:
-    sig = inspect.signature(callable_obj)
-    kwargs: Dict[str, Any] = {}
+def _find_key_by_name(locator: Optional[ComponentLocator], name: str) -> Optional[KeyT]:
+    if not locator:
+        return None
+    for k, md in locator._metadata.items():
+        if md.pico_name == name:
+            return k
+        typ = md.provided_type or md.concrete_class
+        if isinstance(typ, type) and getattr(typ, "__name__", "") == name:
+            return k
+    return None
+
+def _normalize_callable(obj):
+    return getattr(obj, '__func__', obj)
+
+def _get_signature_safe(callable_obj):
+    try:
+        return inspect.signature(callable_obj)
+    except (ValueError, TypeError):
+        wrapped = getattr(callable_obj, '__wrapped__', None)
+        if wrapped is not None:
+            return inspect.signature(wrapped)
+        raise
+
+@functools.lru_cache(maxsize=1024)
+def _analyze_signature_template(callable_obj):
+    callable_obj = _normalize_callable(callable_obj)
+    sig = _get_signature_safe(callable_obj)
+    plan = []
     for name, param in sig.parameters.items():
-        if name in ("self", "cls"):
-            continue
-        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
-            continue
+        if name in ("self", "cls"): continue
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD): continue
         ann = param.annotation
         is_list, elem_t, qual = _extract_list_req(ann)
-        if is_list and pico._locator is not None and isinstance(elem_t, type):
-            keys = _collect_by_type(pico._locator, elem_t, qual)
-            kwargs[name] = [pico.get(k) for k in keys]
+        if is_list:
+            plan.append(("list", name, (elem_t, qual)))
+        else:
+            plan.append(("key", name, ann))
+    return tuple(plan)
+
+def _compile_argplan(callable_obj, pico):
+    template = _analyze_signature_template(callable_obj)
+    locator = pico._locator
+    items = []
+    for kind, name, data in template:
+        if kind == "list":
+            elem_t, qual = data
+            if locator is not None and isinstance(elem_t, type):
+                keys = _collect_by_type(locator, elem_t, qual)
+                items.append(("list", name, tuple(keys)))
             continue
+        ann = data
         if ann is not inspect._empty and isinstance(ann, type):
-            key: KeyT = ann
-        elif ann is not inspect._empty and isinstance(ann, str):
             key = ann
+        elif ann is not inspect._empty and isinstance(ann, str):
+            mapped = _find_key_by_name(locator, ann)
+            key = mapped if mapped is not None else ann
         else:
             key = name
-        kwargs[name] = pico.get(key)
+        items.append(("key", name, key))
+    return tuple(items)
+
+def _resolve_args(callable_obj: Callable[..., Any], pico: "PicoContainer") -> Dict[str, Any]:
+    plan = _compile_argplan(callable_obj, pico)
+    kwargs: Dict[str, Any] = {}
+    tracer = pico._tracer
+    prev = tracer.override_via("constructor")
+    try:
+        for kind, name, data in plan:
+            if kind == "key":
+                tracer.note_param(data if isinstance(data, (str, type)) else name, name)
+                kwargs[name] = pico.get(data)
+            else:
+                vals = [pico.get(k) for k in data]
+                kwargs[name] = vals
+    finally:
+        tracer.restore_via(prev)
     return kwargs
 
 def _needs_async_configure(obj: Any) -> bool:
@@ -445,9 +537,12 @@ class Registrar:
         self._resolver = ConfigResolver(tuple(tree_sources))
         self._adapters = TypeAdapterRegistry()
         self._graph = ObjectGraphBuilder(self._resolver, self._adapters)
+        self._provides_functions: Dict[KeyT, Callable[..., Any]] = {}
         
     def locator(self) -> ComponentLocator:
-        return ComponentLocator(self._metadata, self._indexes)
+        loc = ComponentLocator(self._metadata, self._indexes)
+        setattr(loc, "_provides_functions", dict(self._provides_functions))
+        return loc
 
     def attach_runtime(self, pico, locator: ComponentLocator) -> None:
         for deferred in self._deferred:
@@ -476,24 +571,21 @@ class Registrar:
             return True
         p = set(c.get("profiles") or ())
         if p and not (p & self._profiles):
-            self._log.info("excluded_by_profile name=%s need=%s active=%s", getattr(obj, "__name__", str(obj)), sorted(p), sorted(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):
-                self._log.info("excluded_by_env name=%s env=%s", getattr(obj, "__name__", str(obj)), k)
                 return False
         pred = c.get("predicate")
         if pred is None:
             return True
         try:
             ok = bool(pred())
-        except Exception as e:
-            self._log.info("excluded_by_predicate_error name=%s error=%s", getattr(obj, "__name__", str(obj)), repr(e))
+        except Exception:
             return False
         if not ok:
-            self._log.info("excluded_by_predicate name=%s", getattr(obj, "__name__", str(obj)))
-        return ok
+            return False
+        return True
 
     def _register_component_class(self, cls: type) -> None:
         if not self._enabled_by_condition(cls):
@@ -510,19 +602,48 @@ class Registrar:
             return
         for name in dir(cls):
             try:
-                real = getattr(cls, name)
+                raw = inspect.getattr_static(cls, name)
             except Exception:
                 continue
-            if callable(real) and getattr(real, PICO_INFRA, None) == "provides":
-                if not self._enabled_by_condition(real):
-                    continue
-                k = getattr(real, PICO_KEY)
+            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)
+            if kind == "instance":
                 provider = DeferredProvider(lambda pico, loc, fc=cls, mn=name: _build_method(getattr(_build_class(fc, pico, loc), mn), pico, loc))
-                rt = _get_return_type(real)
-                qset = set(str(q) for q in getattr(real, PICO_META, {}).get("qualifier", ()))
-                sc = getattr(real, 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(real, PICO_META, {}).get("primary")), lazy=bool(getattr(real, PICO_META, {}).get("lazy", False)), infra=getattr(cls, PICO_INFRA, None), pico_name=getattr(real, PICO_NAME, None), scope=sc)
-                self._queue(k, provider, md)
+            else:
+                provider = DeferredProvider(lambda pico, loc, f=fn: _build_method(f, pico, loc))
+            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
+            )
+            self._queue(k, provider, md)
 
     def _register_configuration_class(self, cls: type) -> None:
         if not self._enabled_by_condition(cls):
@@ -551,6 +672,30 @@ class Registrar:
         md = ProviderMetadata(key=target, provided_type=target, concrete_class=None, factory_class=None, factory_method=None, qualifiers=qset, primary=True, lazy=False, infra="configured", pico_name=prefix, scope=sc)
         self._queue(target, provider, md)
 
+    def _register_provides_function(self, fn: Callable[..., Any]) -> None:
+        if not self._enabled_by_condition(fn):
+            return
+        k = getattr(fn, PICO_KEY)
+        provider = DeferredProvider(lambda pico, loc, f=fn: _build_method(f, pico, loc))
+        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
+        )
+        self._queue(k, provider, md)
+        self._provides_functions[k] = fn
+
     def register_module(self, module: Any) -> None:
         for _, obj in inspect.getmembers(module):
             if inspect.isclass(obj):
@@ -569,6 +714,9 @@ class Registrar:
                     self._register_configuration_class(obj)
                 elif infra == "configured":
                     self._register_configured_class(obj)
+        for _, fn in inspect.getmembers(module, predicate=inspect.isfunction):
+            if getattr(fn, PICO_INFRA, None) == "provides":
+                self._register_provides_function(fn)
 
     def _prefix_exists(self, md: ProviderMetadata) -> bool:
         if md.infra != "configured":
@@ -634,6 +782,13 @@ class Registrar:
                 dep = self._find_md_for_type(t)
                 if dep and dep.scope != "singleton":
                     return dep.scope
+        if md.infra == "provides":
+            fn = self._provides_functions.get(md.key)
+            if callable(fn):
+                for t in self._iter_param_types(fn):
+                    dep = self._find_md_for_type(t)
+                    if dep and dep.scope != "singleton":
+                        return dep.scope
         return None
 
     def _promote_scopes(self) -> None:
@@ -681,9 +836,13 @@ class Registrar:
             if isinstance(t, type) and getattr(t, "__name__", "") == name:
                 return k
         return None
-
+        
     def _validate_bindings(self) -> None:
         errors: List[str] = []
+
+        def _fmt(k: KeyT) -> str:
+            return getattr(k, '__name__', str(k))
+
         def _skip_type(t: type) -> bool:
             if t in (str, int, float, bool, bytes):
                 return True
@@ -692,6 +851,7 @@ class Registrar:
             if getattr(t, "_is_protocol", False):
                 return True
             return False
+
         def _should_validate(param: inspect.Parameter) -> bool:
             if param.default is not inspect._empty:
                 return False
@@ -702,18 +862,44 @@ class Registrar:
                 if type(None) in args:
                     return False
             return True
+
         loc = ComponentLocator(self._metadata, self._indexes)
+
         for k, md in self._metadata.items():
             if md.infra == "configuration":
                 continue
+
             callables_to_check: List[Callable[..., Any]] = []
+            loc_name = "unknown"
+
             if md.concrete_class is not None:
                 callables_to_check.append(md.concrete_class.__init__)
-            if md.factory_class is not None and md.factory_method is not None:
-                fn = getattr(md.factory_class, md.factory_method)
-                callables_to_check.append(fn)
+                loc_name = "constructor"
+            elif md.factory_class is not None and md.factory_method is not None:
+                try:
+                    fn = getattr(md.factory_class, md.factory_method)
+                    callables_to_check.append(fn)
+                    loc_name = f"factory {_fmt(md.factory_class)}.{md.factory_method}"
+                except AttributeError:
+                    errors.append(f"Component '{_fmt(k)}' refers to missing factory method '{md.factory_method}' on class '{_fmt(md.factory_class)}'")
+                    continue
+            elif md.infra == "provides":
+                fn = self._provides_functions.get(k)
+                if callable(fn):
+                    callables_to_check.append(fn)
+                    loc_name = f"function {getattr(fn, '__name__', 'unknown')}"
+                else:
+                    continue
+            else:
+                if not md.concrete_class and not md.factory_class and md.override:
+                    continue
+
             for callable_obj in callables_to_check:
-                sig = inspect.signature(callable_obj)
+                try:
+                    sig = inspect.signature(callable_obj)
+                except (ValueError, TypeError):
+                    continue
+
                 for name, param in sig.parameters.items():
                     if name in ("self", "cls"):
                         continue
@@ -721,27 +907,45 @@ class Registrar:
                         continue
                     if not _should_validate(param):
                         continue
+
                     ann = param.annotation
                     is_list, elem_t, qual = _extract_list_req(ann)
+
                     if is_list:
                         if qual:
                             matching = loc.with_qualifier_any(qual).keys()
-                            if not matching:
-                                errors.append(f"{getattr(k,'__name__',k)} expects List[{getattr(elem_t,'__name__',elem_t)}] with qualifier '{qual}' but no matching components exist")
+                            if not matching and isinstance(elem_t, type) and not _skip_type(elem_t):
+                                errors.append(f"{_fmt(k)} ({loc_name}) expects List[{_fmt(elem_t)}] with qualifier '{qual}' but no matching components exist")
                         continue
-                    if isinstance(ann, str):
-                        if ann in self._metadata or self._factory.has(ann) or self._find_md_for_name(ann) is not None:
-                            continue
-                        errors.append(f"{getattr(k,'__name__',k)} depends on string key '{ann}' which is not bound")
+
+                    elif isinstance(ann, str):
+                        key_found_by_name = self._find_md_for_name(ann)
+                        directly_bound = ann in self._metadata or self._factory.has(ann)
+                        if not key_found_by_name and not directly_bound:
+                            errors.append(f"{_fmt(k)} ({loc_name}) depends on string key '{ann}' which is not bound")
+                        continue
+
+                    elif isinstance(ann, type) and not _skip_type(ann):
+                        dep_key_found = self._factory.has(ann) or ann in self._metadata
+                        if not dep_key_found:
+                            assignable_md = self._find_md_for_type(ann)
+                            if assignable_md is None:
+                                by_name_key = self._find_md_for_name(getattr(ann, "__name__", ""))
+                                if by_name_key is None:
+                                    errors.append(f"{_fmt(k)} ({loc_name}) depends on {_fmt(ann)} which is not bound")
                         continue
-                    if isinstance(ann, type) and not _skip_type(ann):
-                        dep = self._find_md_for_type(ann)
-                        if dep is None:
-                            loc_name = "constructor" if callable_obj.__name__ == "__init__" else f"factory {md.factory_class.__name__}.{md.factory_method}"
-                            errors.append(f"{getattr(k,'__name__',k)} {loc_name} depends on {getattr(ann,'__name__',ann)} which is not bound")
+
+                    elif ann is inspect._empty:
+                        name_key = name
+                        key_found_by_name = self._find_md_for_name(name_key)
+                        directly_bound = name_key in self._metadata or self._factory.has(name_key)
+                        if not key_found_by_name and not directly_bound:
+                            errors.append(f"{_fmt(k)} ({loc_name}) depends on parameter '{name}' with no type hint, and key '{name_key}' is not bound")
+                        continue
+                         
         if errors:
             raise InvalidBindingError(errors)
-
+            
     def finalize(self, overrides: Optional[Dict[KeyT, Any]]) -> None:
         self.select_and_bind()
         self._promote_scopes()
@@ -774,7 +978,8 @@ class Registrar:
         self._rebuild_indexes()
         self._validate_bindings()
 
-def init(modules: Union[Any, Iterable[Any]], *, profiles: Tuple[str, ...] = (), allowed_profiles: Optional[Iterable[str]] = None, environ: Optional[Dict[str, str]] = None, overrides: Optional[Dict[KeyT, Any]] = None, logger: Optional[logging.Logger] = None, config: Tuple[ConfigSource, ...] = (), custom_scopes: Optional[Dict[str, "ScopeProtocol"]] = None, validate_only: bool = False, container_id: Optional[str] = None, tree_config: Tuple["TreeSource", ...] = ()) -> PicoContainer:
+
+def init(modules: Union[Any, Iterable[Any]], *, profiles: Tuple[str, ...] = (), allowed_profiles: Optional[Iterable[str]] = None, environ: Optional[Dict[str, str]] = None, overrides: Optional[Dict[KeyT, Any]] = None, logger: Optional[logging.Logger] = None, config: Tuple[ConfigSource, ...] = (), custom_scopes: Optional[Dict[str, "ScopeProtocol"]] = None, validate_only: bool = False, container_id: Optional[str] = None, tree_config: Tuple["TreeSource", ...] = (), observers: Optional[List["ContainerObserver"]] = None,) -> PicoContainer:
     active = tuple(p.strip() for p in profiles if p)
     allowed_set = set(a.strip() for a in allowed_profiles) if allowed_profiles is not None else None
     if allowed_set is not None:
@@ -787,7 +992,14 @@ def init(modules: Union[Any, Iterable[Any]], *, profiles: Tuple[str, ...] = (),
     if custom_scopes:
         for n, impl in custom_scopes.items():
             scopes.register_scope(n, impl)
-    pico = PicoContainer(factory, caches, scopes, container_id=container_id, profiles=active)
+    pico = PicoContainer(
+        factory,
+        caches,
+        scopes,
+        container_id=container_id,
+        profiles=active,
+        observers=observers or [],
+    )
     registrar = Registrar(factory, profiles=active, environ=environ, logger=logger, config=config, tree_sources=tree_config)
     for m in _iter_input_modules(modules):
         registrar.register_module(m)
@@ -797,9 +1009,153 @@ def init(modules: Union[Any, Iterable[Any]], *, profiles: Tuple[str, ...] = (),
             factory.bind(k, prov)
     registrar.finalize(overrides)
     if validate_only:
+        locator = registrar.locator()
+        pico.attach_locator(locator)
+        _fail_fast_cycle_check(pico)
         return pico
     locator = registrar.locator()
     registrar.attach_runtime(pico, locator)
     pico.attach_locator(locator)
+    _fail_fast_cycle_check(pico)
     return pico
 
+def _dependency_keys_for(key: KeyT, pico: "PicoContainer") -> Tuple[KeyT, ...]:
+    loc = pico._locator
+    if not loc:
+        return ()
+    md = loc._metadata.get(key)
+    if not md:
+        return ()
+    if md.concrete_class is not None:
+        fn = md.concrete_class.__init__
+    elif md.factory_class is not None and md.factory_method is not None:
+        fn = getattr(md.factory_class, md.factory_method)
+    else:
+        return ()
+    plan = _compile_argplan(fn, pico)
+    deps: List[KeyT] = []
+    for kind, _, data in plan:
+        if kind == "key":
+            deps.append(data)
+        else:
+            for k in data:
+                deps.append(k)
+    return tuple(deps)
+
+def _get_signature_static(fn: Callable[..., Any]) -> inspect.Signature:
+    return inspect.signature(fn)
+
+def _compile_argplan_static(callable_obj: Callable[..., Any], locator: ComponentLocator) -> Tuple[Tuple[str, str, Any], ...]:
+    sig = _get_signature_static(callable_obj)
+    items: List[Tuple[str, str, Any]] = []
+    for name, param in sig.parameters.items():
+        if name in ("self", "cls"):
+            continue
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+        ann = param.annotation
+        is_list, elem_t, qual = _extract_list_req(ann)
+        if is_list and locator is not None and isinstance(elem_t, type):
+            keys = _collect_by_type(locator, elem_t, qual)
+            items.append(("list", name, tuple(keys)))
+            continue
+        if ann is not inspect._empty and isinstance(ann, type):
+            key: KeyT = ann
+        elif ann is not inspect._empty and isinstance(ann, str):
+            mapped = _find_key_by_name(locator, ann)
+            key = mapped if mapped is not None else ann
+        else:
+            key = name
+        items.append(("key", name, key))
+    return tuple(items)
+
+def _dependency_keys_for_static(md: ProviderMetadata, locator: ComponentLocator) -> Tuple[KeyT, ...]:
+    if md.concrete_class is not None:
+        fn = md.concrete_class.__init__
+    elif md.factory_class is not None and md.factory_method is not None:
+        fn = getattr(md.factory_class, md.factory_method)
+    elif md.infra == "provides":
+        fn = getattr(locator, "_provides_functions", {}).get(md.key)
+        if not callable(fn):
+            return ()
+    else:
+        return ()
+    plan = _compile_argplan_static(fn, locator)
+    deps: List[KeyT] = []
+    for kind, _, data in plan:
+        if kind == "key":
+            deps.append(data)
+        else:
+            for k in data:
+                deps.append(k)
+    return tuple(deps)
+
+def _build_resolution_graph(pico: "PicoContainer") -> Dict[KeyT, Tuple[KeyT, ...]]:
+    loc = pico._locator
+    if not loc:
+        return {}
+
+    def _map_dep_to_bound_key(dep_key: KeyT) -> KeyT:
+        if dep_key in loc._metadata:
+            return dep_key
+        if isinstance(dep_key, type):
+            for k, md in loc._metadata.items():
+                typ = md.provided_type or md.concrete_class
+                if isinstance(typ, type):
+                    try:
+                        if issubclass(typ, dep_key):
+                            return k
+                    except Exception:
+                        continue
+        return dep_key
+
+    graph: Dict[KeyT, Tuple[KeyT, ...]] = {}
+    for key, md in list(loc._metadata.items()):
+        deps: List[KeyT] = []
+        for d in _dependency_keys_for_static(md, loc):
+            mapped = _map_dep_to_bound_key(d)
+            deps.append(mapped)
+        graph[key] = tuple(deps)
+    return graph
+
+
+def _find_cycle(graph: Dict[KeyT, Tuple[KeyT, ...]]) -> Optional[Tuple[KeyT, ...]]:
+    temp: Set[KeyT] = set()
+    perm: Set[KeyT] = set()
+    stack: List[KeyT] = []
+    def visit(n: KeyT) -> Optional[Tuple[KeyT, ...]]:
+        if n in perm:
+            return None
+        if n in temp:
+            try:
+                idx = stack.index(n)
+                return tuple(stack[idx:] + [n])
+            except ValueError:
+                return tuple([n, n])
+        temp.add(n)
+        stack.append(n)
+        for m in graph.get(n, ()):
+            c = visit(m)
+            if c:
+                return c
+        stack.pop()
+        temp.remove(n)
+        perm.add(n)
+        return None
+    for node in graph.keys():
+        c = visit(node)
+        if c:
+            return c
+    return None
+
+def _format_key(k: KeyT) -> str:
+    return getattr(k, "__name__", str(k))
+
+def _fail_fast_cycle_check(pico: "PicoContainer") -> None:
+    graph = _build_resolution_graph(pico)
+    cyc = _find_cycle(graph)
+    if not cyc:
+        return
+    path = " -> ".join(_format_key(k) for k in cyc)
+    raise InvalidBindingError([f"Circular dependency detected: {path}"])
+