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

pico_ioc/container.py

@@ -0,0 +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)
+
+
+class PicoContainer:
+    def __init__(self):
+        self._providers: Dict[Any, Dict[str, Any]] = {}
+        self._singletons: Dict[Any, Any] = {}
+
+    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
+
+    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")
+
+        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]
+
+        # 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, prov in list(self._providers.items()):
+            if not prov["lazy"]:
+                self.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

@@ -0,0 +1,76 @@
+# pico_ioc/decorators.py
+from __future__ import annotations
+import functools
+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(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)
+        setattr(c, COMPONENT_KEY, name if name is not None else c)
+        setattr(c, COMPONENT_LAZY, bool(lazy))
+        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/plugins.py

@@ -0,0 +1,12 @@
+# pico_ioc/plugins.py
+from typing import Protocol, Any
+from .container import Binder, PicoContainer
+
+class PicoPlugin(Protocol):
+    def before_scan(self, package: Any, binder: Binder) -> None: ...
+    def visit_class(self, module: Any, cls: type, binder: Binder) -> None: ...
+    def after_scan(self, package: Any, binder: Binder) -> None: ...
+    def after_bind(self, container: PicoContainer, binder: Binder) -> None: ...
+    def before_eager(self, container: PicoContainer, binder: Binder) -> None: ...
+    def after_ready(self, container: PicoContainer, binder: Binder) -> None: ...
+

pico_ioc/proxy.py

@@ -0,0 +1,77 @@
+# pico_ioc/proxy.py
+
+from typing import Any, Callable
+
+class ComponentProxy:
+    def __init__(self, object_creator: Callable[[], Any]):
+        object.__setattr__(self, "_object_creator", object_creator)
+        object.__setattr__(self, "__real_object", None)
+
+    def _get_real_object(self) -> Any:
+        real_obj = object.__getattribute__(self, "__real_object")
+        if real_obj is None:
+            real_obj = object.__getattribute__(self, "_object_creator")()
+            object.__setattr__(self, "__real_object", real_obj)
+        return real_obj
+
+    @property
+    def __class__(self):
+        return self._get_real_object().__class__
+
+    def __getattr__(self, name): return getattr(self._get_real_object(), name)
+    def __setattr__(self, name, value): setattr(self._get_real_object(), name, value)
+    def __delattr__(self, name): delattr(self._get_real_object(), name)
+    def __str__(self): return str(self._get_real_object())
+    def __repr__(self): return repr(self._get_real_object())
+    def __dir__(self): return dir(self._get_real_object())
+    def __len__(self): return len(self._get_real_object())
+    def __getitem__(self, key): return self._get_real_object()[key]
+    def __setitem__(self, key, value): self._get_real_object()[key] = value
+    def __delitem__(self, key): del self._get_real_object()[key]
+    def __iter__(self): return iter(self._get_real_object())
+    def __reversed__(self): return reversed(self._get_real_object())
+    def __contains__(self, item): return item in self._get_real_object()
+    def __add__(self, other): return self._get_real_object() + other
+    def __sub__(self, other): return self._get_real_object() - other
+    def __mul__(self, other): return self._get_real_object() * other
+    def __matmul__(self, other): return self._get_real_object() @ other
+    def __truediv__(self, other): return self._get_real_object() / other
+    def __floordiv__(self, other): return self._get_real_object() // other
+    def __mod__(self, other): return self._get_real_object() % other
+    def __divmod__(self, other): return divmod(self._get_real_object(), other)
+    def __pow__(self, other, modulo=None): return pow(self._get_real_object(), other, modulo)
+    def __lshift__(self, other): return self._get_real_object() << other
+    def __rshift__(self, other): return self._get_real_object() >> other
+    def __and__(self, other): return self._get_real_object() & other
+    def __xor__(self, other): return self._get_real_object() ^ other
+    def __or__(self, other): return self._get_real_object() | other
+    def __radd__(self, other): return other + self._get_real_object()
+    def __rsub__(self, other): return other - self._get_real_object()
+    def __rmul__(self, other): return other * self._get_real_object()
+    def __rmatmul__(self, other): return other @ self._get_real_object()
+    def __rtruediv__(self, other): return other / self._get_real_object()
+    def __rfloordiv__(self, other): return other // self._get_real_object()
+    def __rmod__(self, other): return other % self._get_real_object()
+    def __rdivmod__(self, other): return divmod(other, self._get_real_object())
+    def __rpow__(self, other): return pow(other, self._get_real_object())
+    def __rlshift__(self, other): return other << self._get_real_object()
+    def __rrshift__(self, other): return other >> self._get_real_object()
+    def __rand__(self, other): return other & self._get_real_object()
+    def __rxor__(self, other): return other ^ self._get_real_object()
+    def __ror__(self, other): return other | self._get_real_object()
+    def __neg__(self): return -self._get_real_object()
+    def __pos__(self): return +self._get_real_object()
+    def __abs__(self): return abs(self._get_real_object())
+    def __invert__(self): return ~self._get_real_object()
+    def __eq__(self, other): return self._get_real_object() == other
+    def __ne__(self, other): return self._get_real_object() != other
+    def __lt__(self, other): return self._get_real_object() < other
+    def __le__(self, other): return self._get_real_object() <= other
+    def __gt__(self, other): return self._get_real_object() > other
+    def __ge__(self, other): return self._get_real_object() >= other
+    def __hash__(self): return hash(self._get_real_object())
+    def __bool__(self): return bool(self._get_real_object())
+    def __call__(self, *args, **kwargs): return self._get_real_object()(*args, **kwargs)
+    def __enter__(self): return self._get_real_object().__enter__()
+    def __exit__(self, exc_type, exc_val, exc_tb): return self._get_real_object().__exit__(exc_type, exc_val, exc_tb)
+

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__
+

pico_ioc/resolver.py

@@ -0,0 +1,110 @@
+# pico_ioc/resolver.py (Python 3.10+)
+
+from __future__ import annotations
+import inspect
+from typing import Any, Annotated, get_args, get_origin, get_type_hints
+
+
+def _get_hints(obj, owner_cls=None) -> dict:
+    """type hints with include_extras=True and correct globals/locals."""
+    mod = inspect.getmodule(obj)
+    g = getattr(mod, "__dict__", {})
+    l = vars(owner_cls) if owner_cls is not None else None
+    return get_type_hints(obj, globalns=g, localns=l, include_extras=True)
+
+
+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", ...].
+    """
+    origin = get_origin(tp) or tp
+    args = get_args(tp) or ()
+    container_kind = list if origin is list else tuple
+
+    if not args:
+        return (object, (), container_kind)
+
+    inner = args[0]
+    if get_origin(inner) is Annotated:
+        base, *extras = get_args(inner)
+        quals = tuple(a for a in extras if isinstance(a, str))
+        return (base, quals, container_kind)
+
+    return (inner, (), container_kind)
+
+
+class Resolver:
+    def __init__(self, container, *, prefer_name_first: bool = True):
+        self.c = container
+        self._prefer_name_first = bool(prefer_name_first)
+
+    def create_instance(self, cls):
+        sig = inspect.signature(cls.__init__)
+        hints = _get_hints(cls.__init__, owner_cls=cls)
+        kwargs = {}
+        for name, param in sig.parameters.items():
+            if name == "self":
+                continue
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+            ann = hints.get(name, param.annotation)
+            try:
+                value = self._resolve_param(name, ann)
+            except NameError:
+                if param.default is not inspect._empty:
+                    continue
+                raise
+            kwargs[name] = value
+        return cls(**kwargs)
+
+    def kwargs_for_callable(self, fn, *, owner_cls=None):
+        sig = inspect.signature(fn)
+        hints = _get_hints(fn, owner_cls=owner_cls)
+        kwargs = {}
+        for name, param in sig.parameters.items():
+            if name == "self":
+                continue
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+            ann = hints.get(name, param.annotation)
+            try:
+                value = self._resolve_param(name, ann)
+            except NameError:
+                if param.default is not inspect._empty:
+                    continue
+                raise
+            kwargs[name] = value
+        return kwargs
+
+    def _resolve_param(self, name: str, ann: Any):
+        # collections (list/tuple) with optional qualifiers via Annotated
+        if _is_collection_hint(ann):
+            base, quals, container_kind = _base_and_qualifiers_from_hint(ann)
+            items = self.c._resolve_all_for_base(base, qualifiers=quals)
+            return list(items) if container_kind is list else tuple(items)
+
+        # precedence: by name > by exact annotation > by MRO > by name again
+        if self._prefer_name_first and self.c.has(name):
+            return self.c.get(name)
+
+        if ann is not inspect._empty and self.c.has(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):
+                    return self.c.get(base)
+
+        if self.c.has(name):
+            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}")
+