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

pico_ioc/__init__.py

@@ -1,10 +1,10 @@
-import functools
-import importlib
-import inspect
-import logging
-import pkgutil
-from contextvars import ContextVar
-from typing import Any, Callable, Dict, Optional, Protocol, Tuple, runtime_checkable
+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
 
 try:
     from ._version import __version__
@@ -17,6 +17,7 @@ __all__ = [
     "Binder",
     "PicoPlugin",
     "init",
+    "reset", 
     "component",
     "factory_component",
     "provides",
@@ -24,385 +25,3 @@ __all__ = [
     "create_instance",
 ]
 
-_scanning: ContextVar[bool] = ContextVar("pico_scanning", default=False)
-_resolving: ContextVar[bool] = ContextVar("pico_resolving", default=False)
-
-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 has(self, key: Any) -> bool:
-        return key in self._providers or key in self._singletons
-
-    def get(self, key: Any) -> Any:
-        if _scanning.get() and not _resolving.get():
-            raise RuntimeError("pico-ioc: re-entrant container access during scan.")
-        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"]()
-        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:
-                self.get(key)
-
-class Binder:
-    def __init__(self, container: PicoContainer):
-        self._c = container
-
-    def bind(self, key: Any, provider: Callable[[], Any], *, lazy: bool = False):
-        self._c.bind(key, provider, lazy=lazy)
-
-    def has(self, key: Any) -> bool:
-        return self._c.has(key)
-
-    def get(self, key: Any) -> Any:
-        return self._c.get(key)
-
-def factory_component(cls):
-    setattr(cls, '_is_factory_component', True)
-    return cls
-
-def provides(key: Any, *, lazy: bool = False):
-    def decorator(func):
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):
-            return func(*args, **kwargs)
-        setattr(wrapper, '_provides_name', key)
-        setattr(wrapper, '_pico_lazy', bool(lazy))
-        return wrapper
-    return decorator
-
-def component(cls=None, *, name: Any = None, lazy: bool = False):
-    def decorator(c):
-        setattr(c, '_is_component', True)
-        setattr(c, '_component_key', name if name is not None else c)
-        setattr(c, '_component_lazy', bool(lazy))
-        return c
-    return decorator(cls) if cls else decorator
-
-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)
-
-def resolve_param(container: PicoContainer, p: inspect.Parameter) -> Any:
-    if p.name == 'self' or p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
-        raise RuntimeError("Invalid param for resolution")
-    if container.has(p.name):
-        return container.get(p.name)
-    ann = p.annotation
-    if ann is not inspect._empty and container.has(ann):
-        return container.get(ann)
-    if ann is not inspect._empty:
-        try:
-            for base in getattr(ann, "__mro__", ())[1:]:
-                if base is object:
-                    break
-                if container.has(base):
-                    return container.get(base)
-        except Exception:
-            pass
-    if container.has(str(p.name)):
-        return container.get(str(p.name))
-    key = p.name if ann is inspect._empty else ann
-    return container.get(key)
-
-def create_instance(cls: type, container: PicoContainer) -> Any:
-    """
-    Instantiate `cls` with constructor DI from `container`.
-
-    Resolution rules:
-      - Skip `self`, *args, **kwargs.
-      - Try resolve_param(...) for each parameter.
-      - If resolve_param raises NameError AND the parameter has a default,
-        skip injecting it so Python uses the default value.
-      - Otherwise, propagate the error.
-
-    This preserves the "name > type > MRO > str(name)" precedence in resolve_param,
-    while making defaulted, annotated parameters truly optional.
-    """
-    sig = inspect.signature(cls.__init__)
-    deps: Dict[str, Any] = {}
-
-    tok = _resolving.set(True)
-    try:
-        for p in sig.parameters.values():
-            if p.name == 'self' or p.kind in (
-                inspect.Parameter.VAR_POSITIONAL,
-                inspect.Parameter.VAR_KEYWORD,
-            ):
-                continue
-
-            try:
-                deps[p.name] = resolve_param(container, p)
-            except NameError:
-                if p.default is not inspect._empty:
-                    continue
-                raise
-    finally:
-        _resolving.reset(tok)
-
-    return cls(**deps)
-
-
-@runtime_checkable
-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: ...
-
-def _scan_and_configure(
-    package_or_name,
-    container: PicoContainer,
-    *,
-    exclude: Optional[Callable[[str], bool]] = None,
-    plugins: Tuple[PicoPlugin, ...] = (),
-):
-    package = importlib.import_module(package_or_name) if isinstance(package_or_name, str) else package_or_name
-    logging.info(f"Scanning in '{package.__name__}'...")
-    binder = Binder(container)
-
-    for pl in plugins:
-        try:
-            if hasattr(pl, "before_scan"):
-                pl.before_scan(package, binder)
-        except Exception:
-            logging.exception("Plugin before_scan failed")
-
-    component_classes, factory_classes = [], []
-    for _, name, _ in pkgutil.walk_packages(package.__path__, package.__name__ + '.'):
-        if exclude and exclude(name):
-            logging.info(f"Skipping module {name} (excluded)")
-            continue
-        try:
-            module = importlib.import_module(name)
-            for _, obj in inspect.getmembers(module, inspect.isclass):
-                for pl in plugins:
-                    try:
-                        if hasattr(pl, "visit_class"):
-                            pl.visit_class(module, obj, binder)
-                    except Exception:
-                        logging.exception("Plugin visit_class failed")
-                if getattr(obj, '_is_component', False):
-                    component_classes.append(obj)
-                elif getattr(obj, '_is_factory_component', False):
-                    factory_classes.append(obj)
-        except Exception as e:
-            logging.warning(f"Module {name} not processed: {e}")
-
-    for pl in plugins:
-        try:
-            if hasattr(pl, "after_scan"):
-                pl.after_scan(package, binder)
-        except Exception:
-            logging.exception("Plugin after_scan failed")
-            
-    for component_cls in component_classes:
-        key = getattr(component_cls, '_component_key', component_cls)
-        is_lazy = bool(getattr(component_cls, '_component_lazy', False))
-
-        def provider_factory(lazy=is_lazy, cls=component_cls):
-            def _factory():
-                if lazy:
-                    return ComponentProxy(lambda: create_instance(cls, container))
-                return create_instance(cls, container)
-            return _factory
-
-        container.bind(key, provider_factory(), lazy=is_lazy)
-
-
-    def _resolve_method_kwargs(meth) -> Dict[str, Any]:
-        sig = inspect.signature(meth)
-        deps = {}
-        tok = _resolving.set(True)
-        try:
-            for p in sig.parameters.values():
-                if p.name == 'self' or p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
-                    continue
-                try:
-                    deps[p.name] = resolve_param(container, p)
-                except NameError:
-                    if p.default is not inspect._empty:
-                        continue
-                    raise
-        finally:
-            _resolving.reset(tok)
-        return deps
-
-    for factory_cls in factory_classes:
-        try:
-            factory_instance = create_instance(factory_cls, container)
-
-            for name, func in inspect.getmembers(factory_cls, predicate=inspect.isfunction):
-                provides_key = getattr(func, '_provides_name', None)
-                if provides_key is None:
-                    continue
-
-                is_lazy = bool(getattr(func, '_pico_lazy', False))
-
-                bound_method = getattr(factory_instance, name, None)
-                if bound_method is None:
-                    bound_method = func.__get__(factory_instance, factory_cls)
-
-                fn_meta_src = getattr(bound_method, '__func__', bound_method)
-                if getattr(fn_meta_src, '_provides_name', None) is not None:
-                    provides_key = getattr(fn_meta_src, '_provides_name')
-                    is_lazy = bool(getattr(fn_meta_src, '_pico_lazy', is_lazy))
-
-                def make_provider(m=bound_method, lazy=is_lazy):
-                    def _factory():
-                        kwargs = _resolve_method_kwargs(m)
-
-                        def _call():
-                            return m(**kwargs)
-
-                        if lazy:
-                            return ComponentProxy(lambda: _call())
-                        return _call()
-                    return _factory
-
-                container.bind(provides_key, make_provider(), lazy=is_lazy)
-        except Exception:
-            logging.exception(f"Error in factory {factory_cls.__name__}")
-
-
-
-_container: Optional[PicoContainer] = None
-
-def init(
-    root_package,
-    *,
-    exclude: Optional[Callable[[str], bool]] = None,
-    auto_exclude_caller: bool = True,
-    plugins: Tuple[PicoPlugin, ...] = (),
-):
-    global _container
-    if _container:
-        return _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)
-    _container = PicoContainer()
-    binder = Binder(_container)
-    logging.info("Initializing pico-ioc...")
-    tok = _scanning.set(True)
-    try:
-        _scan_and_configure(root_package, _container, exclude=combined_exclude, plugins=plugins)
-    finally:
-        _scanning.reset(tok)
-    for pl in plugins:
-        try:
-            if hasattr(pl, "after_bind"):
-                pl.after_bind(_container, binder)
-        except Exception:
-            logging.exception("Plugin after_bind failed")
-    for pl in plugins:
-        try:
-            if hasattr(pl, "before_eager"):
-                pl.before_eager(_container, binder)
-        except Exception:
-            logging.exception("Plugin before_eager failed")
-    _container._eager_instantiate_all()
-    for pl in plugins:
-        try:
-            if hasattr(pl, "after_ready"):
-                pl.after_ready(_container, binder)
-        except Exception:
-            logging.exception("Plugin after_ready failed")
-    logging.info("Container configured and ready.")
-    return _container
-

pico_ioc/_state.py

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

pico_ioc/_version.py

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

pico_ioc/api.py

@@ -0,0 +1,74 @@
+import inspect
+import logging
+from typing import Callable, Optional, Tuple
+from .container import PicoContainer, Binder
+from .plugins import PicoPlugin
+from .scanner import scan_and_configure
+from . import _state
+
+
+def reset() -> None:
+    _state._container = None
+
+
+def init(
+    root_package,
+    *,
+    exclude: Optional[Callable[[str], bool]] = None,
+    auto_exclude_caller: bool = True,
+    plugins: Tuple[PicoPlugin, ...] = (),
+    reuse: bool = True,
+) -> PicoContainer:
+    if reuse and _state._container:
+        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)
+
+    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)
+
+    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")
+
+    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")
+
+    logging.info("Container configured and ready.")
+    _state._container = container
+    return container
+

pico_ioc/container.py

@@ -0,0 +1,43 @@
+# pico_ioc/container.py
+
+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 has(self, key: Any) -> bool:
+        return key in self._providers or key in self._singletons
+
+
+    def get(self, key: Any) -> Any:
+        if _scanning.get() and not _resolving.get():
+            raise RuntimeError("pico-ioc: re-entrant container access during scan.")
+
+        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"]()
+        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:
+                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)
+

pico_ioc/decorators.py

@@ -0,0 +1,33 @@
+# pico_ioc/decorators.py
+
+import functools
+from typing import Any
+
+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"
+
+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)
+        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
+

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/resolver.py

@@ -0,0 +1,58 @@
+# pico_ioc/resolver.py
+
+import inspect
+from typing import Any, Dict, Optional
+from .container import PicoContainer
+from .typing_utils import evaluated_hints, resolve_annotation_to_type
+from ._state import _resolving
+
+class Resolver:
+    def __init__(self, container: PicoContainer):
+        self.c = container
+
+    def _resolve_by_mro(self, ann) -> Optional[Any]:
+        try:
+            for base in getattr(ann, "__mro__", ())[1:]:
+                if base is object: break
+                if self.c.has(base): return self.c.get(base)
+        except Exception:
+            pass
+        return None
+
+    def _resolve_param(self, name: str, ann) -> Any:
+        if 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:
+            mro_hit = self._resolve_by_mro(ann)
+            if mro_hit is not None: return mro_hit
+        if self.c.has(str(name)): return self.c.get(str(name))
+        key = name if ann is inspect._empty else ann
+        return self.c.get(key)
+
+    def kwargs_for_callable(self, fn, owner_cls=None) -> Dict[str, Any]:
+        sig = inspect.signature(fn)
+        hints = evaluated_hints(fn, owner_cls=owner_cls)
+        deps: Dict[str, Any] = {}
+
+        tok = _resolving.set(True)
+        try:
+            for p in sig.parameters.values():
+                if p.name == "self" or p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                    continue
+                raw_ann = hints.get(p.name, p.annotation)
+                ann = resolve_annotation_to_type(raw_ann, fn, owner_cls)
+                try:
+                    deps[p.name] = self._resolve_param(p.name, ann)
+                except NameError:
+                    if p.default is not inspect._empty:
+                        continue
+                    missing = ann if ann is not inspect._empty else p.name
+                    raise NameError(f"No provider found for key: {missing}")
+            return deps
+        finally:
+            _resolving.reset(tok)
+
+    def create_instance(self, cls: type) -> Any:
+        kw = self.kwargs_for_callable(cls.__init__, owner_cls=cls)
+        return cls(**kw)
+

pico_ioc/scanner.py

@@ -0,0 +1,105 @@
+import importlib
+import inspect
+import logging
+import pkgutil
+from typing import Any, Callable, Optional, Tuple, List
+
+from .container import PicoContainer, Binder
+from .decorators import (
+    COMPONENT_FLAG,
+    COMPONENT_KEY,
+    COMPONENT_LAZY,
+    FACTORY_FLAG,
+    PROVIDES_KEY,
+    PROVIDES_LAZY,
+)
+from .proxy import ComponentProxy
+from .resolver import Resolver
+from .plugins import PicoPlugin
+
+
+def scan_and_configure(
+    package_or_name: Any,
+    container: PicoContainer,
+    *,
+    exclude: Optional[Callable[[str], bool]] = None,
+    plugins: Tuple[PicoPlugin, ...] = (),
+):
+    package = importlib.import_module(package_or_name) if isinstance(package_or_name, str) else package_or_name
+    logging.info(f"Scanning in '{package.__name__}'...")
+    binder = Binder(container)
+    resolver = Resolver(container)
+
+    for pl in plugins:
+        try:
+            getattr(pl, "before_scan", lambda *a, **k: None)(package, binder)
+        except Exception:
+            logging.exception("Plugin before_scan failed")
+
+    comp_classes: List[type] = []
+    factory_classes: List[type] = []
+
+    for _, name, _ in pkgutil.walk_packages(package.__path__, package.__name__ + "."):
+        if exclude and exclude(name):
+            logging.info(f"Skipping module {name} (excluded)")
+            continue
+        try:
+            module = importlib.import_module(name)
+            for _, obj in inspect.getmembers(module, inspect.isclass):
+                for pl in plugins:
+                    try:
+                        getattr(pl, "visit_class", lambda *a, **k: None)(module, obj, binder)
+                    except Exception:
+                        logging.exception("Plugin visit_class failed")
+                if getattr(obj, COMPONENT_FLAG, False):
+                    comp_classes.append(obj)
+                elif getattr(obj, FACTORY_FLAG, False):
+                    factory_classes.append(obj)
+        except Exception as e:
+            logging.warning(f"Module {name} not processed: {e}")
+
+    for pl in plugins:
+        try:
+            getattr(pl, "after_scan", lambda *a, **k: None)(package, binder)
+        except Exception:
+            logging.exception("Plugin after_scan failed")
+
+    # Register @component classes (bind ONLY by declared key)
+    for cls in comp_classes:
+        key = getattr(cls, COMPONENT_KEY, cls)
+        is_lazy = bool(getattr(cls, COMPONENT_LAZY, False))
+
+        def provider_factory(c=cls, lazy=is_lazy):
+            def _factory():
+                if lazy:
+                    return ComponentProxy(lambda: resolver.create_instance(c))
+                return resolver.create_instance(c)
+            return _factory
+
+        container.bind(key, provider_factory(), lazy=is_lazy)
+
+    # Register @factory_component methods marked with @provides
+    for fcls in factory_classes:
+        try:
+            finst = resolver.create_instance(fcls)
+            for name, func in inspect.getmembers(fcls, predicate=inspect.isfunction):
+                pk = getattr(func, PROVIDES_KEY, None)
+                if pk is None:
+                    continue
+                is_lazy = bool(getattr(func, PROVIDES_LAZY, False))
+                bound = getattr(finst, name, func.__get__(finst, fcls))
+
+                def make_provider(m=bound, lazy=is_lazy):
+                    def _factory():
+                        kwargs = resolver.kwargs_for_callable(m, owner_cls=fcls)
+
+                        def _call():
+                            return m(**kwargs)
+
+                        return ComponentProxy(lambda: _call()) if lazy else _call()
+                    return _factory
+
+                container.bind(pk, make_provider(), lazy=is_lazy)
+        except Exception:
+            logging.exception(f"Error in factory {fcls.__name__}")
+

pico_ioc/typing_utils.py

@@ -0,0 +1,24 @@
+# pico_ioc/typing_utils.py
+
+import sys, typing
+
+def evaluated_hints(func, owner_cls=None) -> dict:
+    try:
+        module = sys.modules.get(func.__module__)
+        globalns = getattr(module, "__dict__", {})
+        localns = vars(owner_cls) if owner_cls is not None else {}
+        return typing.get_type_hints(func, globalns=globalns, localns=localns)
+    except Exception:
+        return {}
+
+def resolve_annotation_to_type(ann, func, owner_cls=None):
+    if not isinstance(ann, str):
+        return ann
+    try:
+        module = sys.modules.get(func.__module__)
+        globalns = getattr(module, "__dict__", {})
+        localns = vars(owner_cls) if owner_cls is not None else {}
+        return eval(ann, globalns, localns)
+    except Exception:
+        return ann
+

{pico_ioc-0.5.1.dist-info → pico_ioc-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 0.5.1
+Version: 0.6.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -45,12 +45,6 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
 
-Got it ✅
-Here’s your **updated README.md in full English**, keeping all original sections but now including the **name-first resolution** feature and new tests section.
-
----
-
-````markdown
 # 📦 Pico-IoC: A Minimalist IoC Container for Python
 
 [![PyPI](https://img.shields.io/pypi/v/pico-ioc.svg)](https://pypi.org/project/pico-ioc/)
@@ -162,10 +156,10 @@ print(COUNTER["value"])               # 1
 
 Starting with **v0.5.0**, Pico-IoC enforces **name-first resolution**:
 
-1. **Parameter name** (highest priority)
-2. **Exact type annotation**
-3. **MRO fallback** (walk base classes)
-4. **String(name)**
+1. **Parameter name** (highest priority)  
+2. **Exact type annotation**  
+3. **MRO fallback** (walk base classes)  
+4. **String(name)**  
 
 This means that if a dependency could match both by name and type, **the name match wins**.
 
@@ -191,6 +185,18 @@ class NameVsTypeFactory:
 container = init(__name__)
 assert container.get("choose") == "by-name"
 ```
+---
+
+## 📝 Notes on Annotations (PEP 563)
+
+Pico-IoC fully supports **postponed evaluation of annotations**
+(`from __future__ import annotations`, a.k.a. **PEP 563**) in Python 3.8–3.10.
+
+* Type hints are evaluated with `typing.get_type_hints` and safely resolved.
+* Missing dependencies always raise a **`NameError`**, never a `TypeError`.
+* Behavior is consistent across Python 3.8+ and Python 3.11+ (where PEP 563 is no longer default).
+
+This means you can freely use either direct type hints or string-based annotations in your components and factories, without breaking dependency injection.
 
 ---
 

pico_ioc-0.6.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pico_ioc/__init__.py,sha256=1UwdG8Ax7syyvN9uUUPUr_Gzf-TswqFGzoIHx0dG7b0,572
+pico_ioc/_state.py,sha256=hXBOob3SwVYcord8eln4Fe2dzJJTDovh-dAll2DRkvg,225
+pico_ioc/_version.py,sha256=CBY3jsC-9HCm7eZ6CKD-sYLCejqOJ1pYWPQM4LGIXcI,22
+pico_ioc/api.py,sha256=5ZiVqggvgS_ln8AwzpCRZall6OyeRX_JADwW1I1tDdM,2281
+pico_ioc/container.py,sha256=OqR4giSesWOAdbVvy5Z9GpK20h3PWlkYdA0xrqVTbTw,1479
+pico_ioc/decorators.py,sha256=nKbcfzMQc_QKmVRA6Z2IHqlmimkD3Xy-JMzMXZuM6Ps,900
+pico_ioc/plugins.py,sha256=JbI-28VLGJaik7ysXi3L-YGTGxhqwJH4W5QYuWSruDE,589
+pico_ioc/proxy.py,sha256=-e3Z9z7Bc_2wxswwUJI_s8AfvCTps8f8RWUJ9RuEp7E,4606
+pico_ioc/resolver.py,sha256=xCDDBXGFpSay3dp_MKam83921xmaVpCNnHISgyR6JCs,2225
+pico_ioc/scanner.py,sha256=T-E4VMUanU1o1R8c2LUMDuhvIJFonap82UzOOtkNza4,3775
+pico_ioc/typing_utils.py,sha256=lpRusK1o5o36o278wSyuDVsGM3D0LGqFB0n_LOQ83F0,770
+pico_ioc-0.6.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-0.6.0.dist-info/METADATA,sha256=SdV4U9PjQZNrF1Z06IF4Z_8r4SYFoaTDwYH-Y0W2Nys,10039
+pico_ioc-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-0.6.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-0.6.0.dist-info/RECORD,,

pico_ioc-0.5.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-pico_ioc/__init__.py,sha256=zWSJSAIgpZ_bXNi_6s88Lmql181ECyIy_Yh7hc5SOd8,16487
-pico_ioc/_version.py,sha256=s8Yq9Om1yBxrMA7xYQ5Y13Paeuxnq99NxhyjuPlnH6A,22
-pico_ioc-0.5.1.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
-pico_ioc-0.5.1.dist-info/METADATA,sha256=dgeFxNxy4tCDXNWgUqirSbjK80CTAlhsNWrumI5z47A,9623
-pico_ioc-0.5.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-0.5.1.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-0.5.1.dist-info/RECORD,,