pico-ioc 0.6.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

pico_ioc/__init__.py

@@ -1,27 +1,31 @@
-from ._version import __version__
-from .container import PicoContainer, Binder
-from .decorators import component, factory_component, provides
-from .plugins import PicoPlugin
-from .resolver import Resolver
-from .api import init, reset
-from .proxy import ComponentProxy
+# pico_ioc/__init__.py
 
 try:
     from ._version import __version__
 except Exception:
     __version__ = "0.0.0"
 
+from .container import PicoContainer, Binder
+from .decorators import component, factory_component, provides, plugin, Qualifier, qualifier
+from .plugins import PicoPlugin
+from .resolver import Resolver
+from .api import init, reset
+from .proxy import ComponentProxy
+
 __all__ = [
     "__version__",
     "PicoContainer",
     "Binder",
     "PicoPlugin",
+    "ComponentProxy",
     "init",
-    "reset", 
+    "reset",
     "component",
     "factory_component",
     "provides",
-    "resolve_param",
-    "create_instance",
+    "plugin",
+    "Qualifier",
+    "qualifier",
+    "Resolver",
 ]
 

pico_ioc/_state.py

@@ -1,8 +1,10 @@
 # pico_ioc/_state.py
 from contextvars import ContextVar
+from typing import Optional
 
 _scanning: ContextVar[bool] = ContextVar("pico_scanning", default=False)
 _resolving: ContextVar[bool] = ContextVar("pico_resolving", default=False)
 
 _container = None
+_root_name: Optional[str] = None
 

pico_ioc/_version.py

@@ -1 +1 @@
-__version__ = '0.6.0'
+__version__ = '1.0.0'

pico_ioc/api.py

@@ -1,6 +1,10 @@
+# pico_ioc/api.py
+
 import inspect
 import logging
+from contextlib import contextmanager
 from typing import Callable, Optional, Tuple
+
 from .container import PicoContainer, Binder
 from .plugins import PicoPlugin
 from .scanner import scan_and_configure
@@ -8,7 +12,9 @@ from . import _state
 
 
 def reset() -> None:
+    """Reset the global container."""
     _state._container = None
+    _state._root_name = None
 
 
 def init(
@@ -19,56 +25,104 @@ def init(
     plugins: Tuple[PicoPlugin, ...] = (),
     reuse: bool = True,
 ) -> PicoContainer:
-    if reuse and _state._container:
+    """
+    Initialize and configure a PicoContainer by scanning a root package.
+    """
+    root_name = root_package if isinstance(root_package, str) else getattr(root_package, "__name__", None)
+
+    # Reuse only if the existing container was built for the same root
+    if reuse and _state._container and _state._root_name == root_name:
         return _state._container
 
-    combined_exclude = exclude
-    if auto_exclude_caller:
-        try:
-            caller_frame = inspect.stack()[1].frame
-            caller_module = inspect.getmodule(caller_frame)
-            caller_name = getattr(caller_module, "__name__", None)
-        except Exception:
-            caller_name = None
-        if caller_name:
-            if combined_exclude is None:
-                def combined_exclude(mod: str, _caller=caller_name):
-                    return mod == _caller
-            else:
-                prev = combined_exclude
-                def combined_exclude(mod: str, _caller=caller_name, _prev=prev):
-                    return mod == _caller or _prev(mod)
+    combined_exclude = _build_exclude(exclude, auto_exclude_caller, root_name=root_name)
 
     container = PicoContainer()
     binder = Binder(container)
     logging.info("Initializing pico-ioc...")
 
-    tok = _state._scanning.set(True)
-    try:
-        scan_and_configure(root_package, container, exclude=combined_exclude, plugins=plugins)
-    finally:
-        _state._scanning.reset(tok)
+    with _scanning_flag():
+        scan_and_configure(
+            root_package,
+            container,
+            exclude=combined_exclude,
+            plugins=plugins,
+        )
 
-    for pl in plugins:
-        try:
-            getattr(pl, "after_bind", lambda *a, **k: None)(container, binder)
-        except Exception:
-            logging.exception("Plugin after_bind failed")
-    for pl in plugins:
-        try:
-            getattr(pl, "before_eager", lambda *a, **k: None)(container, binder)
-        except Exception:
-            logging.exception("Plugin before_eager failed")
+    _run_hooks(plugins, "after_bind", container, binder)
+    _run_hooks(plugins, "before_eager", container, binder)
 
     container.eager_instantiate_all()
 
-    for pl in plugins:
-        try:
-            getattr(pl, "after_ready", lambda *a, **k: None)(container, binder)
-        except Exception:
-            logging.exception("Plugin after_ready failed")
+    _run_hooks(plugins, "after_ready", container, binder)
 
     logging.info("Container configured and ready.")
     _state._container = container
+    _state._root_name = root_name  # remember which root this container represents
     return container
 
+
+# -------------------- helpers --------------------
+
+def _build_exclude(
+    exclude: Optional[Callable[[str], bool]],
+    auto_exclude_caller: bool,
+    *,
+    root_name: Optional[str] = None,
+) -> Optional[Callable[[str], bool]]:
+    """
+    Compose the exclude predicate. When auto_exclude_caller=True, exclude only
+    the exact calling module, but never exclude modules under the root being scanned.
+    """
+    if not auto_exclude_caller:
+        return exclude
+
+    caller = _get_caller_module_name()
+    if not caller:
+        return exclude
+
+    def _under_root(mod: str) -> bool:
+        return bool(root_name) and (mod == root_name or mod.startswith(root_name + "."))
+
+    if exclude is None:
+        return lambda mod, _caller=caller: (mod == _caller) and not _under_root(mod)
+
+    prev = exclude
+    return lambda mod, _caller=caller, _prev=prev: (((mod == _caller) and not _under_root(mod)) or _prev(mod))
+
+
+def _get_caller_module_name() -> Optional[str]:
+    """Return the module name that called `init`."""
+    try:
+        f = inspect.currentframe()
+        # frame -> _get_caller_module_name -> _build_exclude -> init
+        if f and f.f_back and f.f_back.f_back and f.f_back.f_back.f_back:
+            mod = inspect.getmodule(f.f_back.f_back.f_back)
+            return getattr(mod, "__name__", None)
+    except Exception:
+        pass
+    return None
+
+
+def _run_hooks(
+    plugins: Tuple[PicoPlugin, ...],
+    hook_name: str,
+    container: PicoContainer,
+    binder: Binder,
+) -> None:
+    for pl in plugins:
+        try:
+            fn = getattr(pl, hook_name, None)
+            if fn:
+                fn(container, binder)
+        except Exception:
+            logging.exception("Plugin %s failed", hook_name)
+
+
+@contextmanager
+def _scanning_flag():
+    tok = _state._scanning.set(True)
+    try:
+        yield
+    finally:
+        _state._scanning.reset(tok)
+

pico_ioc/container.py

@@ -1,43 +1,155 @@
 # pico_ioc/container.py
+from __future__ import annotations
+import inspect
+from typing import Any, Dict, get_origin, get_args, Annotated
+import typing as _t 
+
+from .decorators import QUALIFIERS_KEY
+from . import _state  # re-entrancy guard
+
+
+class Binder:
+    def __init__(self, container: "PicoContainer"):
+        self._c = container
+
+    def bind(self, key: Any, provider, *, lazy: bool):
+        self._c.bind(key, provider, lazy=lazy)
+
+    def has(self, key: Any) -> bool:
+        return self._c.has(key)
+
+    def get(self, key: Any):
+        return self._c.get(key)
 
-from typing import Any, Callable, Dict
-from ._state import _scanning, _resolving
 
 class PicoContainer:
     def __init__(self):
         self._providers: Dict[Any, Dict[str, Any]] = {}
         self._singletons: Dict[Any, Any] = {}
 
-    def bind(self, key: Any, provider: Callable[[], Any], *, lazy: bool):
-        self._providers[key] = {"factory": provider, "lazy": bool(lazy)}
+    def bind(self, key: Any, provider, *, lazy: bool):
+        meta = {"factory": provider, "lazy": bool(lazy)}
+        try:
+            q = getattr(key, QUALIFIERS_KEY, ())
+        except Exception:
+            q = ()
+        meta["qualifiers"] = tuple(q) if q else ()
+        self._providers[key] = meta
 
     def has(self, key: Any) -> bool:
-        return key in self._providers or key in self._singletons
+        return key in self._providers
 
+    def get(self, key: Any):
+        # block only when scanning and NOT currently resolving a dependency
+        if _state._scanning.get() and not _state._resolving.get():
+            raise RuntimeError("re-entrant container access during scan")
 
-    def get(self, key: Any) -> Any:
-        if _scanning.get() and not _resolving.get():
-            raise RuntimeError("pico-ioc: re-entrant container access during scan.")
+        prov = self._providers.get(key)
+        if prov is None:
+            raise NameError(f"No provider found for key {key!r}")
 
         if key in self._singletons:
             return self._singletons[key]
-        prov = self._providers.get(key)
-        if prov is None:
-            raise NameError(f"No provider found for key: {key}")
-        instance = prov["factory"]()
+
+        # mark resolving around factory execution
+        tok = _state._resolving.set(True)
+        try:
+            instance = prov["factory"]()
+        finally:
+            _state._resolving.reset(tok)
+
+        # memoize always (both lazy and non-lazy after first get)
         self._singletons[key] = instance
         return instance
 
-
     def eager_instantiate_all(self):
-        for key, meta in list(self._providers.items()):
-            if not meta.get("lazy", False) and key not in self._singletons:
+        for key, prov in list(self._providers.items()):
+            if not prov["lazy"]:
                 self.get(key)
 
-class Binder:
-    def __init__(self, container: PicoContainer):
-        self._c = container
-    def bind(self, key, provider, *, lazy=False): self._c.bind(key, provider, lazy=lazy)
-    def has(self, key) -> bool: return self._c.has(key)
-    def get(self, key): return self._c.get(key)
+    def get_all(self, base_type: Any):
+        return tuple(self._resolve_all_for_base(base_type, qualifiers=()))
+
+    def get_all_qualified(self, base_type: Any, *qualifiers: str):
+        return tuple(self._resolve_all_for_base(base_type, qualifiers=qualifiers))
+
+    def _resolve_all_for_base(self, base_type: Any, qualifiers=()):
+        matches = []
+        for provider_key, meta in self._providers.items():
+            cls = provider_key if isinstance(provider_key, type) else None
+            if cls is None:
+                continue
+
+            # Avoid self-inclusion loops: if the class itself requires a collection
+            # of `base_type` in its __init__, don't treat it as an implementation
+            # of `base_type` when building that collection.
+            if _requires_collection_of_base(cls, base_type):
+                continue
+
+            if _is_compatible(cls, base_type):
+                prov_qs = meta.get("qualifiers", ())
+                if all(q in prov_qs for q in qualifiers):
+                    inst = self.get(provider_key)
+                    matches.append(inst)
+        return matches
+
+
+def _is_protocol(t) -> bool:
+    return getattr(t, "_is_protocol", False) is True
+
+
+def _is_compatible(cls, base) -> bool:
+    try:
+        if isinstance(base, type) and issubclass(cls, base):
+            return True
+    except TypeError:
+        pass
+
+    if _is_protocol(base):
+        # simple structural check: ensure methods/attrs declared on the Protocol exist on the class
+        names = set(getattr(base, "__annotations__", {}).keys())
+        names.update(n for n in getattr(base, "__dict__", {}).keys() if not n.startswith("_"))
+        for n in names:
+            if n.startswith("__") and n.endswith("__"):
+                continue
+            if not hasattr(cls, n):
+                return False
+        return True
+
+    return False
+
+def _requires_collection_of_base(cls, base) -> bool:
+    """
+    Return True if `cls.__init__` has any parameter annotated as a collection
+    (list/tuple, including Annotated variants) of `base`. This prevents treating
+    `cls` as an implementation of `base` while building that collection,
+    avoiding recursion.
+    """
+    try:
+        sig = inspect.signature(cls.__init__)
+    except Exception:
+        return False
+
+    try:
+        from .resolver import _get_hints  # type: ignore
+        hints = _get_hints(cls.__init__, owner_cls=cls)
+    except Exception:
+        hints = {}
+
+    for name, param in sig.parameters.items():
+        if name == "self":
+            continue
+        ann = hints.get(name, param.annotation)
+        origin = get_origin(ann) or ann
+        if origin in (list, tuple, _t.List, _t.Tuple):
+            inner = (get_args(ann) or (object,))[0]
+            # Unwrap Annotated[T, ...] si aparece
+            if get_origin(inner) is Annotated:
+                args = get_args(inner)
+                if args:
+                    inner = args[0]
+            if inner is base:
+                return True
+    return False
+
 

pico_ioc/decorators.py

@@ -1,28 +1,36 @@
 # pico_ioc/decorators.py
-
+from __future__ import annotations
 import functools
-from typing import Any
+from typing import Any, Iterable
 
 COMPONENT_FLAG = "_is_component"
 COMPONENT_KEY = "_component_key"
 COMPONENT_LAZY = "_component_lazy"
+
 FACTORY_FLAG = "_is_factory_component"
 PROVIDES_KEY = "_provides_name"
 PROVIDES_LAZY = "_pico_lazy"
 
+PLUGIN_FLAG = "_is_pico_plugin"
+QUALIFIERS_KEY = "_pico_qualifiers"
+
+
 def factory_component(cls):
     setattr(cls, FACTORY_FLAG, True)
     return cls
 
+
 def provides(key: Any, *, lazy: bool = False):
-    def dec(func):
-        @functools.wraps(func)
-        def w(*a, **k): return func(*a, **k)
+    def dec(fn):
+        @functools.wraps(fn)
+        def w(*a, **k):
+            return fn(*a, **k)
         setattr(w, PROVIDES_KEY, key)
         setattr(w, PROVIDES_LAZY, bool(lazy))
         return w
     return dec
 
+
 def component(cls=None, *, name: Any = None, lazy: bool = False):
     def dec(c):
         setattr(c, COMPONENT_FLAG, True)
@@ -31,3 +39,38 @@ def component(cls=None, *, name: Any = None, lazy: bool = False):
         return c
     return dec(cls) if cls else dec
 
+
+def plugin(cls):
+    setattr(cls, PLUGIN_FLAG, True)
+    return cls
+
+
+class Qualifier(str):
+    __slots__ = ()  # tiny memory win; immutable like str
+
+
+def qualifier(*qs: Qualifier):
+    def dec(cls):
+        current: Iterable[Qualifier] = getattr(cls, QUALIFIERS_KEY, ())
+        seen = set(current)
+        merged = list(current)
+        for q in qs:
+            if q not in seen:
+                merged.append(q)
+                seen.add(q)
+        setattr(cls, QUALIFIERS_KEY, tuple(merged))
+        return cls
+    return dec
+
+
+__all__ = [
+    # decorators
+    "component", "factory_component", "provides", "plugin", "qualifier",
+    # qualifier type
+    "Qualifier",
+    # metadata keys (exported for advanced use/testing)
+    "COMPONENT_FLAG", "COMPONENT_KEY", "COMPONENT_LAZY",
+    "FACTORY_FLAG", "PROVIDES_KEY", "PROVIDES_LAZY",
+    "PLUGIN_FLAG", "QUALIFIERS_KEY",
+]
+

pico_ioc/public_api.py

@@ -0,0 +1,76 @@
+# pico_ioc/public_api.py
+
+from __future__ import annotations
+import importlib
+import inspect
+import pkgutil
+import sys
+from types import ModuleType
+from typing import Dict, Iterable, Optional, Tuple
+
+from .decorators import COMPONENT_FLAG, FACTORY_FLAG, PLUGIN_FLAG
+
+
+def export_public_symbols_decorated(
+    *packages: str,
+    include_also: Optional[Iterable[str]] = None,
+    include_plugins: bool = True,
+):
+    index: Dict[str, Tuple[str, str]] = {}
+
+    def _collect(m: ModuleType):
+        names = getattr(m, "__all__", None)
+        if isinstance(names, (list, tuple, set)):
+            for n in names:
+                if hasattr(m, n):
+                    index.setdefault(n, (m.__name__, n))
+            return
+
+        for n, obj in m.__dict__.items():
+            if not inspect.isclass(obj):
+                continue
+            is_component = getattr(obj, COMPONENT_FLAG, False)
+            is_factory = getattr(obj, FACTORY_FLAG, False)
+            is_plugin = include_plugins and getattr(obj, PLUGIN_FLAG, False)
+            if is_component or is_factory or is_plugin:
+                index.setdefault(n, (m.__name__, n))
+
+    for pkg_name in packages:
+        try:
+            base = importlib.import_module(pkg_name)
+        except Exception:
+            continue
+        if hasattr(base, "__path__"):
+            prefix = base.__name__ + "."
+            for _, modname, _ in pkgutil.walk_packages(base.__path__, prefix):
+                try:
+                    m = importlib.import_module(modname)
+                except Exception:
+                    continue
+                _collect(m)
+        else:
+            _collect(base)
+
+    for qual in tuple(include_also or ()):
+        modname, _, attr = qual.partition(":")
+        if modname and attr:
+            try:
+                m = importlib.import_module(modname)
+                if hasattr(m, attr):
+                    index.setdefault(attr, (m.__name__, attr))
+            except Exception:
+                pass
+
+    def __getattr__(name: str):
+        try:
+            modname, attr = index[name]
+        except KeyError as e:
+            raise AttributeError(f"module has no attribute {name!r}") from e
+        mod = sys.modules.get(modname) or importlib.import_module(modname)
+        return getattr(mod, attr)
+
+    def __dir__():
+        return sorted(index.keys())
+
+    return __getattr__, __dir__
+