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

pico_ioc/scanner.py

@@ -1,4 +1,4 @@
-# pico_ioc/scanner.py
+from __future__ import annotations
 import importlib
 import inspect
 import logging
@@ -6,7 +6,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,
@@ -17,14 +17,13 @@ from .decorators import (
     PROVIDES_LAZY,
     COMPONENT_TAGS,
     PROVIDES_TAGS,
-    INTERCEPTOR_META,
+    INFRA_META,
 )
 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(
     package_or_name: Any,
@@ -32,103 +31,66 @@ def scan_and_configure(
     *,
     exclude: Optional[Callable[[str], bool]] = None,
     plugins: Tuple[PicoPlugin, ...] = (),
-) -> 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
-    """
+) -> tuple[int, int, list[tuple[type, dict]]]:
     package = _as_module(package_or_name)
     logging.info("Scanning in '%s'...", getattr(package, "__name__", repr(package)))
-
     binder = Binder(container)
     resolver = Resolver(container)
-
     run_plugin_hook(plugins, "before_scan", package, binder)
-
-    comp_classes, factory_classes, interceptor_decls = _collect_decorated(
+    comp_classes, factory_classes, infra_decls = _collect_decorated(
         package=package,
         exclude=exclude,
         plugins=plugins,
         binder=binder,
     )
-
     run_plugin_hook(plugins, "after_scan", package, binder)
-
     _register_component_classes(classes=comp_classes, container=container, resolver=resolver)
     _register_factory_classes(factory_classes=factory_classes, container=container, resolver=resolver)
-
-    return len(comp_classes), len(factory_classes), interceptor_decls
-
-
-# -------------------- Helpers --------------------
+    return len(comp_classes), len(factory_classes), infra_decls
 
 def _as_module(package_or_name: Any) -> ModuleType:
     if isinstance(package_or_name, str):
         return importlib.import_module(package_or_name)
     if hasattr(package_or_name, "__spec__"):
-        return package_or_name  # type: ignore[return-value]
+        return package_or_name
     raise TypeError("package_or_name must be a module or importable package name (str).")
 
-
 def _iter_package_modules(package: ModuleType) -> Iterable[str]:
-    """Yield fully-qualified module names under a package (recursive)."""
     try:
-        pkg_path = package.__path__  # type: ignore[attr-defined]
+        pkg_path = package.__path__
     except Exception:
         return
     prefix = package.__name__ + "."
     for _finder, name, _is_pkg in pkgutil.walk_packages(pkg_path, prefix):
         yield name
 
-
 def _collect_decorated(
     *,
     package: ModuleType,
     exclude: Optional[Callable[[str], bool]],
     plugins: Tuple[PicoPlugin, ...],
     binder: Binder,
-) -> Tuple[List[type], List[type], List[tuple[Any, dict]]]:
+) -> Tuple[List[type], List[type], List[tuple[type, dict]]]:
     comps: List[type] = []
     facts: List[type] = []
-    interceptors: List[tuple[Any, dict]] = []
+    infras: List[tuple[type, 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)))
+        infra_m = getattr(cls, INFRA_META, None)
+        if infra_m:
+            infras.append((cls, dict(infra_m)))
+        for _nm, _fn in inspect.getmembers(cls, predicate=inspect.isfunction):
+            pass
 
     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,11 +102,10 @@ 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
+    return comps, facts, infras
 
 def _register_component_classes(
     *,
@@ -156,10 +117,17 @@ 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)
 
-
 def _register_factory_classes(
     *,
     factory_classes: List[type],
@@ -168,7 +136,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)
@@ -177,21 +144,29 @@ def _register_factory_classes(
         except Exception:
             logging.exception("Error in factory %s", fcls.__name__)
             continue
-
-        for attr_name, func in inspect.getmembers(fcls, predicate=inspect.isfunction):
+        raw_dict = getattr(fcls, "__dict__", {})
+        for attr_name, attr in inspect.getmembers(fcls):
+            func = None
+            raw = raw_dict.get(attr_name, None)
+            if isinstance(raw, classmethod):
+                func = raw.__func__
+            elif isinstance(raw, staticmethod):
+                func = raw.__func__
+            elif inspect.isfunction(attr):
+                func = attr
+            if func is None:
+                continue
             provided_key = getattr(func, PROVIDES_KEY, None)
             if provided_key is None:
                 continue
-
             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))
+            if isinstance(raw, (classmethod, staticmethod)):
+                bound = getattr(fcls, attr_name)
+            else:
+                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,41 @@
+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_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.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 1.3.0
+Version: 1.5.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,20 @@ tox
 
 ---
 
+## 📜 Overview
+
+See [OVERVIEW.md](.llm/OVERVIEW.md) Just need a quick summary?
+---
+
+## 🔔 Important Changes
+
+### 1.5.0 (2025-09-17)
+- Introduced **`@infrastructure`** classes for bootstrap-time configuration.  
+  → They can query the model, add interceptors, wrap/replace providers, and adjust tags/qualifiers.  
+- Added new **around-style interceptors** (`MethodInterceptor.invoke`, `ContainerInterceptor.around_*`) with deterministic ordering.  
+- **Removed legacy `@interceptor` API** (before/after/error style). All interceptors must be migrated to the new contracts.  
+
+---
 ## 📜 Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.

pico_ioc-1.5.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+pico_ioc/__init__.py,sha256=Nlj8wsCtOz1uGC9eg7GICsGc4EecU2t9AkY74E1hx_s,1400
+pico_ioc/_state.py,sha256=C98XQZIfKy98j8fzR730eUCoqSnCkRkxUS4bH7mp73c,2154
+pico_ioc/_version.py,sha256=wShy9YfBfroz0HjRH_aNNehkEu1_PLsd_GjTU5aCDPk,22
+pico_ioc/api.py,sha256=-zouzi8Uel7IXpiBYwra6ctqT71LLslcvU1trS4kKh8,8359
+pico_ioc/builder.py,sha256=lwhKliYYonar4JOUi-Nfa8sej06mwSUp0bvKBJLAYes,9007
+pico_ioc/config.py,sha256=J3k7_2vRB2HCpikzeMzT4Ut9COFM4kcydkwZorncqSk,12317
+pico_ioc/container.py,sha256=Chbi8Mhz_OlhD03tf1l4hQq2yGDpELL0eNKtjyjn0us,6389
+pico_ioc/decorators.py,sha256=LSMW5DYfQIV2y60E4tIVprMDUc4M7qCNCe7Pz5nN0Hg,3448
+pico_ioc/infra.py,sha256=IvYA2kliG6opMG8SXX6eneWCQ6tBfSeSCiLq0-f9rJ8,7924
+pico_ioc/interceptors.py,sha256=ZJjIRyTgHh9CTRpNZwTjM8iKvMLIw5OBQ7DrpF29HHY,3465
+pico_ioc/plugins.py,sha256=GP7WEMshggQ-FEjiShkcuLrSMxfueUnhbY9I8PcIyPU,1039
+pico_ioc/policy.py,sha256=p7maTHNfU-zoaz3j7CY4P3ry-bYfaGxAOklcTAuF6dY,8648
+pico_ioc/proxy.py,sha256=2XR5mwNTEpYzZFUCcFJW1psSgOgEFooeO91_2wdnRnk,6403
+pico_ioc/public_api.py,sha256=E3sArCoI1xxkIw7xQBvLYAWcIoVJjcq1s0kH-0qIVDE,2383
+pico_ioc/resolver.py,sha256=Fi4dHY4NuqxNxZwVVtBR1lBnhZSTBd3dDXzr8lRNe-g,4191
+pico_ioc/scanner.py,sha256=ieJ1A2UPWLqfybjPdWQowEx7ZCkN9693pa8sUc83LGE,6612
+pico_ioc/scope.py,sha256=pdSKcO14jt7_rB5ymLpbBI9qS9FbdvTGZfPj3Mc0Znc,1705
+pico_ioc/utils.py,sha256=OyhOKnyepwGQ_uQKlQLt-fymEV1bQ6hCq4Me7h3dfco,1002
+pico_ioc-1.5.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-1.5.0.dist-info/METADATA,sha256=11GMlO6Z1S-PhiLBBHD5gTLfrpTxAR8q-HC6zFfHDwk,10844
+pico_ioc-1.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-1.5.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-1.5.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,,