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

pico_ioc/resolver.py

@@ -1,15 +1,16 @@
-# pico_ioc/resolver.py (Python 3.10+)
-
+# src/pico_ioc/resolver.py
 from __future__ import annotations
+
 import inspect
-from typing import Any, Annotated, get_args, get_origin, get_type_hints, Callable
+from typing import Any, Annotated, Callable, get_args, get_origin, get_type_hints
 from contextvars import ContextVar
 
 
 _path: ContextVar[list[tuple[str, str]]] = ContextVar("pico_resolve_path", default=[])
 
+
 def _get_hints(obj, owner_cls=None) -> dict:
-    """type hints with include_extras=True and correct globals/locals."""
+    """Return type hints with include_extras=True, using correct globals/locals."""
     mod = inspect.getmodule(obj)
     g = getattr(mod, "__dict__", {})
     l = vars(owner_cls) if owner_cls is not None else None
@@ -17,15 +18,14 @@ def _get_hints(obj, owner_cls=None) -> dict:
 
 
 def _is_collection_hint(tp) -> bool:
-    """True if tp is a list[...] or tuple[...]."""
     origin = get_origin(tp) or tp
     return origin in (list, tuple)
 
 
 def _base_and_qualifiers_from_hint(tp):
     """
-    Extract (base, qualifiers, container_kind) from a collection hint.
-    Supports list[T] / tuple[T] and Annotated[T, "qual1", ...].
+    Extract (base, qualifiers, container_kind) from a type hint.
+    Supports list[T], tuple[T], Annotated[T, "qual1", ...].
     """
     origin = get_origin(tp) or tp
     args = get_args(tp) or ()
@@ -48,12 +48,13 @@ class Resolver:
         self.c = container
         self._prefer_name_first = bool(prefer_name_first)
 
+    # --- core resolution ---
 
     def _resolve_dependencies_for_callable(self, fn: Callable, owner_cls: Any = None) -> dict:
         sig = inspect.signature(fn)
         hints = _get_hints(fn, owner_cls=owner_cls)
         kwargs = {}
-    
+
         path_owner = getattr(owner_cls, "__name__", getattr(fn, "__qualname__", "callable"))
         if fn.__name__ == "__init__" and owner_cls:
             path_owner = f"{path_owner}.__init__"
@@ -61,23 +62,18 @@ class Resolver:
         for name, param in sig.parameters.items():
             if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD) or name == "self":
                 continue
-        
+
             ann = hints.get(name, param.annotation)
             st = _path.get()
             _path.set(st + [(path_owner, name)])
             try:
-                value = self._resolve_param(name, ann)
-                kwargs[name] = value
+                kwargs[name] = self._resolve_param(name, ann)
             except NameError as e:
                 if param.default is not inspect.Parameter.empty:
                     _path.set(st)
                     continue
-
-                # If the error is already formatted with a chain, re-raise to preserve the full context.
                 if "(required by" in str(e):
                     raise
-
-                # Otherwise, this is a fresh error; add the full chain for the first time.
                 chain = " -> ".join(f"{owner}.{param}" for owner, param in _path.get())
                 raise NameError(f"{e} (required by {chain})") from e
             finally:
@@ -87,43 +83,50 @@ class Resolver:
         return kwargs
 
     def create_instance(self, cls: type) -> Any:
-        """Creates an instance of a class by resolving its __init__ dependencies."""
-        constructor_kwargs = self._resolve_dependencies_for_callable(cls.__init__, owner_cls=cls)
-        return cls(**constructor_kwargs)
+        """Instantiate a class by resolving its __init__ dependencies."""
+        ctor_kwargs = self._resolve_dependencies_for_callable(cls.__init__, owner_cls=cls)
+        return cls(**ctor_kwargs)
 
     def kwargs_for_callable(self, fn: Callable, *, owner_cls: Any = None) -> dict:
-        """Resolves all keyword arguments for any callable."""
+        """Resolve all keyword arguments for any callable."""
         return self._resolve_dependencies_for_callable(fn, owner_cls=owner_cls)
 
+    # --- param resolution ---
 
     def _notify_resolve(self, key, ann, quals=()):
         for ci in getattr(self.c, "_container_interceptors", ()):
-            try: ci.on_resolve(key, ann, tuple(quals) if quals else ())
-            except Exception: pass
+            try:
+                ci.on_resolve(key, ann, tuple(quals) if quals else ())
+            except Exception:
+                pass
 
     def _resolve_param(self, name: str, ann: Any):
-        # Colecciones (list/tuple)
+        # collections
         if _is_collection_hint(ann):
-            base, quals, container_kind = _base_and_qualifiers_from_hint(ann)
+            base, quals, kind = _base_and_qualifiers_from_hint(ann)
             self._notify_resolve(base, ann, quals)
             items = self.c._resolve_all_for_base(base, qualifiers=quals)
-            return list(items) if container_kind is list else tuple(items)
+            return list(items) if kind is list else tuple(items)
 
-        # Precedencias
+        # precedence
         if self._prefer_name_first and self.c.has(name):
             self._notify_resolve(name, ann, ())
             return self.c.get(name)
+
         if ann is not inspect._empty and self.c.has(ann):
             self._notify_resolve(ann, ann, ())
             return self.c.get(ann)
+
         if ann is not inspect._empty and isinstance(ann, type):
             for base in ann.__mro__[1:]:
                 if self.c.has(base):
                     self._notify_resolve(base, ann, ())
                     return self.c.get(base)
+
         if self.c.has(name):
             self._notify_resolve(name, ann, ())
             return self.c.get(name)
 
         missing = ann if ann is not inspect._empty else name
         raise NameError(f"No provider found for key {missing!r}")
+

pico_ioc/scanner.py

@@ -1,4 +1,6 @@
-# pico_ioc/scanner.py
+# src/pico_ioc/scanner.py
+from __future__ import annotations
+
 import importlib
 import inspect
 import logging
@@ -6,7 +8,7 @@ import pkgutil
 from types import ModuleType
 from typing import Any, Callable, Optional, Tuple, List, Iterable
 
-from .plugins import run_plugin_hook
+from .plugins import run_plugin_hook, PicoPlugin
 from .container import PicoContainer, Binder
 from .decorators import (
     COMPONENT_FLAG,
@@ -21,9 +23,9 @@ from .decorators import (
 )
 from .proxy import ComponentProxy
 from .resolver import Resolver
-from .plugins import PicoPlugin
 from . import _state
 from .utils import _provider_from_class, _provider_from_callable
+from .config import is_config_component, build_component_instance, ConfigRegistry
 
 
 def scan_and_configure(
@@ -35,12 +37,12 @@ def scan_and_configure(
 ) -> tuple[int, int, list[tuple[Any, dict]]]:
     """
     Scan a package, bind components/factories, and collect interceptor declarations.
-    Returns: (component_count, factory_count, interceptor_decls)
 
-    interceptor_decls contains entries of the form:
-      - (cls, meta)                       for class-level @interceptor on a class
-      - (fn, meta)                        for module-level function with @interceptor
-      - ((owner_cls, fn), meta)           for methods on a class decorated with @interceptor
+    Returns: (component_count, factory_count, interceptor_decls)
+      - interceptor_decls entries:
+          (cls, meta)                        for @interceptor class
+          (fn, meta)                         for @interceptor function
+          ((owner_cls, fn), meta)            for @interceptor methods
     """
     package = _as_module(package_or_name)
     logging.info("Scanning in '%s'...", getattr(package, "__name__", repr(package)))
@@ -65,7 +67,7 @@ def scan_and_configure(
     return len(comp_classes), len(factory_classes), interceptor_decls
 
 
-# -------------------- Helpers --------------------
+# -------------------- helpers --------------------
 
 def _as_module(package_or_name: Any) -> ModuleType:
     if isinstance(package_or_name, str):
@@ -98,37 +100,30 @@ def _collect_decorated(
     interceptors: List[tuple[Any, dict]] = []
 
     def _collect_from_class(cls: type):
-        # Class decorators
         if getattr(cls, COMPONENT_FLAG, False):
             comps.append(cls)
         elif getattr(cls, FACTORY_FLAG, False):
             facts.append(cls)
 
-        # Class-level interceptor (decorated class itself)
         meta_class = getattr(cls, INTERCEPTOR_META, None)
         if meta_class:
             interceptors.append((cls, dict(meta_class)))
 
-        # Method-level interceptors
         for _nm, fn in inspect.getmembers(cls, predicate=inspect.isfunction):
             meta_m = getattr(fn, INTERCEPTOR_META, None)
             if meta_m:
-                # Preserve the owner to allow proper binding (self) later
                 interceptors.append(((cls, fn), dict(meta_m)))
 
     def _visit_module(module: ModuleType):
-        # Classes
         for _name, obj in inspect.getmembers(module, inspect.isclass):
             run_plugin_hook(plugins, "visit_class", module, obj, binder)
             _collect_from_class(obj)
 
-        # Module-level functions that declare interceptors
         for _name, fn in inspect.getmembers(module, predicate=inspect.isfunction):
             meta = getattr(fn, INTERCEPTOR_META, None)
             if meta:
                 interceptors.append((fn, dict(meta)))
 
-    # Walk submodules
     for mod_name in _iter_package_modules(package):
         if exclude and exclude(mod_name):
             logging.info("Skipping module %s (excluded)", mod_name)
@@ -140,12 +135,12 @@ def _collect_decorated(
             continue
         _visit_module(module)
 
-    # Also visit the root module itself (in case it's a single-file module)
     if not hasattr(package, "__path__"):
         _visit_module(package)
 
     return comps, facts, interceptors
 
+
 def _register_component_classes(
     *,
     classes: List[type],
@@ -156,7 +151,15 @@ def _register_component_classes(
         key = getattr(cls, COMPONENT_KEY, cls)
         is_lazy = bool(getattr(cls, COMPONENT_LAZY, False))
         tags = tuple(getattr(cls, COMPONENT_TAGS, ()))
-        provider = _provider_from_class(cls, resolver=resolver, lazy=is_lazy)
+        if is_config_component(cls):
+            registry: ConfigRegistry | None = getattr(container, "_config_registry", None)
+            def _prov(_c=cls, _reg=registry):
+                if _reg is None:
+                    raise RuntimeError(f"No config registry found to build {_c.__name__}")
+                return build_component_instance(_c, _reg)
+            provider = (lambda p=_prov: ComponentProxy(p)) if is_lazy else _prov
+        else:
+            provider = _provider_from_class(cls, resolver=resolver, lazy=is_lazy)
         container.bind(key, provider, lazy=is_lazy, tags=tags)
 
 
@@ -168,7 +171,6 @@ def _register_factory_classes(
 ) -> None:
     for fcls in factory_classes:
         try:
-            # Prevent accidental container access recursion while constructing factories
             tok_res = _state._resolving.set(True)
             try:
                 finst = resolver.create_instance(fcls)
@@ -186,12 +188,10 @@ def _register_factory_classes(
             is_lazy = bool(getattr(func, PROVIDES_LAZY, False))
             tags = tuple(getattr(func, PROVIDES_TAGS, ()))
 
-            # bind the method to the concrete factory instance
             bound = getattr(finst, attr_name, func.__get__(finst, fcls))
             prov = _provider_from_callable(bound, owner_cls=fcls, resolver=resolver, lazy=is_lazy)
 
             if isinstance(provided_key, type):
-                # Mark for aliasing policy pipeline and ensure uniqueness of the provider key
                 try:
                     setattr(prov, "_pico_alias_for", provided_key)
                 except Exception:

pico_ioc/scope.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .container import PicoContainer
+
+class ScopedContainer(PicoContainer):
+    def __init__(self, built_container: PicoContainer, base: Optional[PicoContainer], strict: bool):
+        super().__init__(providers=getattr(built_container, "_providers", {}).copy())
+        
+        self._active_profiles = getattr(built_container, "_active_profiles", ())
+        
+        base_method_its = getattr(base, "_method_interceptors", ()) if base else ()
+        base_container_its = getattr(base, "_container_interceptors", ()) if base else ()
+        
+        self._method_interceptors = base_method_its
+        self._container_interceptors = base_container_its
+        self._seen_interceptor_types = {type(it) for it in (base_method_its + base_container_its)}
+
+        for it in getattr(built_container, "_method_interceptors", ()):
+            self.add_method_interceptor(it)
+        for it in getattr(built_container, "_container_interceptors", ()):
+            self.add_container_interceptor(it)
+
+        self._base = base
+        self._strict = strict
+
+        if base:
+            self._singletons.update(getattr(base, "_singletons", {}))
+
+    def __enter__(self): return self
+    def __exit__(self, exc_type, exc, tb): return False
+
+    def has(self, key: Any) -> bool:
+        if super().has(key): return True
+        if not self._strict and self._base is not None:
+            return self._base.has(key)
+        return False
+
+    def get(self, key: Any):
+        try:
+            return super().get(key)
+        except NameError as e:
+            if not self._strict and self._base is not None and self._base.has(key):
+                return self._base.get(key)
+            raise e

{pico_ioc-1.3.0.dist-info → pico_ioc-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 1.3.0
+Version: 1.4.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -221,6 +221,12 @@ tox
 
 ---
 
+## 📜 Overview
+
+See [OVERVIEW.md](.llm/OVERVIEW.md) Just need a quick summary?
+
+---
+
 ## 📜 Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.

pico_ioc-1.4.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+pico_ioc/__init__.py,sha256=s_9v-pMM5X7r5vhbzaOmQQEHBLOmZCV7o6QNtRcfMAU,1282
+pico_ioc/_state.py,sha256=C98XQZIfKy98j8fzR730eUCoqSnCkRkxUS4bH7mp73c,2154
+pico_ioc/_version.py,sha256=EyMGX1ADFzN6XVXHWbJUtKPONYKeFkvWoKIFPDDB2I8,22
+pico_ioc/api.py,sha256=cc9c3db6_dIfeobP_VvFRpNV9qNIsIPbUct5X9mmW9w,8348
+pico_ioc/builder.py,sha256=ZvIpOaAzBpByw-u5V52GM5cJAMH_E_5FMDLlgyqd-g4,11379
+pico_ioc/config.py,sha256=J3k7_2vRB2HCpikzeMzT4Ut9COFM4kcydkwZorncqSk,12317
+pico_ioc/container.py,sha256=V9X0qvNPZYU80C65X3Dqifek6RWt9kgEwG0CkX1Hpow,6461
+pico_ioc/decorators.py,sha256=Jyq7PhSM3uFVfBEaCq6x_mFV9V3B5fTEK4o3I6ZvG5A,4492
+pico_ioc/interceptors.py,sha256=rBdpI7ca5L30N-zR7LKroCIc5FgfNb9M5P7OEGw-TtY,1955
+pico_ioc/plugins.py,sha256=GP7WEMshggQ-FEjiShkcuLrSMxfueUnhbY9I8PcIyPU,1039
+pico_ioc/policy.py,sha256=p7maTHNfU-zoaz3j7CY4P3ry-bYfaGxAOklcTAuF6dY,8648
+pico_ioc/proxy.py,sha256=VJA-QaO8yvejcHmX5mlXMHfyuyXFxD7cazONSzBGrf0,6308
+pico_ioc/public_api.py,sha256=E3sArCoI1xxkIw7xQBvLYAWcIoVJjcq1s0kH-0qIVDE,2383
+pico_ioc/resolver.py,sha256=clIS9wwhOKzIwzBQFXxCrmPX2gM2X2eVyS8P_VEeyDw,4798
+pico_ioc/scanner.py,sha256=TmDLkklO-e2LBoVducQD4-uuZKFDg_dMwgwO9vM8-pU,7129
+pico_ioc/scope.py,sha256=5oRCir1Dqu8Jlgl_R-q900my1u6_7zq5VUbq8ahV280,1754
+pico_ioc/utils.py,sha256=OyhOKnyepwGQ_uQKlQLt-fymEV1bQ6hCq4Me7h3dfco,1002
+pico_ioc-1.4.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-1.4.0.dist-info/METADATA,sha256=DdvaybzEQOnC-HD563NJZqMDL7zwY3SnEpLGwjPxVzU,10346
+pico_ioc-1.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-1.4.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-1.4.0.dist-info/RECORD,,

pico_ioc-1.3.0.dist-info/RECORD

@@ -1,20 +0,0 @@
-pico_ioc/__init__.py,sha256=Vl0nnRou3BZY1QSUOSyZ8-PFIFrz979DAzhXp0KYvIg,1014
-pico_ioc/_state.py,sha256=XG3Q8NsRN-Di5MrWn6kLzJXg25PXp2_qAzfgytNoP-s,1021
-pico_ioc/_version.py,sha256=zi_LaUT_OsChAtsPXbOeRpQkCohSsOyeXfavQPM0GoE,22
-pico_ioc/api.py,sha256=PbR9_VX3ipxgv7-vKq1TyjKC75RqyDr65QUCG4i7eeI,9172
-pico_ioc/builder.py,sha256=QPn1yC3JQYkjV08XpCAIFs95Bi0VQG5NZnSXKx4IgsI,10730
-pico_ioc/container.py,sha256=YCrjAhChHtDcPBg1Zz0PnMbY-6x6V313nA1liPNaUaM,6306
-pico_ioc/decorators.py,sha256=jhJxpaR9wCeBsNm1W0ziTCF3C0LGhu866-9x4IJ9-4U,3581
-pico_ioc/interceptors.py,sha256=-ZH-AG4h_6vUgTJGbP8YESlODhOEkdC6r82GHTRrKxk,1978
-pico_ioc/plugins.py,sha256=GP7WEMshggQ-FEjiShkcuLrSMxfueUnhbY9I8PcIyPU,1039
-pico_ioc/policy.py,sha256=XQs8Nr7aTq0xbNPGaeFiBgJCI65r5rXK4yQdhhQuLjM,12054
-pico_ioc/proxy.py,sha256=ZQ0g5QT32QV_v72N9oUWtQRnTh5An66GPtvaF1HtNp8,6187
-pico_ioc/public_api.py,sha256=E3sArCoI1xxkIw7xQBvLYAWcIoVJjcq1s0kH-0qIVDE,2383
-pico_ioc/resolver.py,sha256=qCzyjsfq59b_XEa5LNAgWzPniqoJYxyG-mXn2fzqFsk,5063
-pico_ioc/scanner.py,sha256=VjIW6e2nsYuI1pm38RX8yIGs7SUrvuKHPN5vgTss3h4,7257
-pico_ioc/utils.py,sha256=OyhOKnyepwGQ_uQKlQLt-fymEV1bQ6hCq4Me7h3dfco,1002
-pico_ioc-1.3.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
-pico_ioc-1.3.0.dist-info/METADATA,sha256=GRIv4XBIAY8vFFXv0BVFyT4lVqryoUEQU9qF6jOlftc,10259
-pico_ioc-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-1.3.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-1.3.0.dist-info/RECORD,,