pico-ioc 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

pico_ioc/__init__.py

@@ -1,18 +1,32 @@
-import functools, inspect, pkgutil, importlib, logging
-from typing import Callable, Any, Optional, Dict
+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
 
 try:
     from ._version import __version__
 except Exception:
     __version__ = "0.0.0"
 
-__all__ = ["__version__"]
+__all__ = [
+    "__version__",
+    "PicoContainer",
+    "Binder",
+    "PicoPlugin",
+    "init",
+    "component",
+    "factory_component",
+    "provides",
+    "resolve_param",
+    "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]] = {}
@@ -26,9 +40,7 @@ class PicoContainer:
 
     def get(self, key: Any) -> Any:
         if _scanning.get() and not _resolving.get():
-            raise RuntimeError(
-                "pico-ioc: re-entrant container access during scan."
-            )
+            raise RuntimeError("pico-ioc: re-entrant container access during scan.")
         if key in self._singletons:
             return self._singletons[key]
         prov = self._providers.get(key)
@@ -43,6 +55,40 @@ class PicoContainer:
             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]):
@@ -117,8 +163,7 @@ class ComponentProxy:
     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:
+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):
@@ -140,10 +185,44 @@ def _resolve_param(container: PicoContainer, p: inspect.Parameter) -> Any:
     key = p.name if ann is inspect._empty else ann
     return container.get(key)
 
+def create_instance(cls: type, container: PicoContainer) -> Any:
+    sig = inspect.signature(cls.__init__)
+    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
+            deps[p.name] = resolve_param(container, p)
+    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):
+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):
@@ -152,12 +231,24 @@ def _scan_and_configure(package_or_name, container: PicoContainer, exclude: Opti
         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 factory_cls in factory_classes:
         try:
             sig = inspect.signature(factory_cls.__init__)
@@ -173,36 +264,28 @@ def _scan_and_configure(package_or_name, container: PicoContainer, exclude: Opti
                             return m()
                         return _factory
                     container.bind(key, make_provider(), lazy=is_lazy)
-        except Exception as e:
-            logging.error(f"Error in factory {factory_cls.__name__}: {e}", exc_info=True)
+        except Exception:
+            logging.exception(f"Error in factory {factory_cls.__name__}")
     for component_cls in component_classes:
         key = getattr(component_cls, '_component_key', component_cls)
         is_lazy = bool(getattr(component_cls, '_component_lazy', False))
-        def create_component(cls=component_cls):
-            sig = inspect.signature(cls.__init__)
-            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
-                    deps[p.name] = _resolve_param(container, p)
-            finally:
-                _resolving.reset(tok)
-            return cls(**deps)
-        def provider_factory(lazy=is_lazy, maker=create_component):
+        def provider_factory(lazy=is_lazy, cls=component_cls):
             def _factory():
                 if lazy:
-                    return ComponentProxy(maker)
-                return maker()
+                    return ComponentProxy(lambda: create_instance(cls, container))
+                return create_instance(cls, container)
             return _factory
         container.bind(key, provider_factory(), lazy=is_lazy)
 
+_container: Optional[PicoContainer] = None
 
-_container = None
-
-
-def init(root_package, *, exclude: Optional[Callable[[str], bool]] = None, auto_exclude_caller: bool = True):
+def init(
+    root_package,
+    *,
+    exclude: Optional[Callable[[str], bool]] = None,
+    auto_exclude_caller: bool = True,
+    plugins: Tuple[PicoPlugin, ...] = (),
+):
     global _container
     if _container:
         return _container
@@ -223,17 +306,37 @@ def init(root_package, *, exclude: Optional[Callable[[str], bool]] = None, auto_
                 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)
+        _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
 
 
+
 def factory_component(cls):
     setattr(cls, '_is_factory_component', True)
     return cls

pico_ioc/_version.py

@@ -1 +1 @@
-__version__ = '0.3.1'
+__version__ = '0.4.0'

{pico_ioc-0.3.1.dist-info → pico_ioc-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 0.3.1
+Version: 0.4.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 Project-URL: Homepage, https://github.com/dperezcabrera/pico-ioc
@@ -219,6 +219,88 @@ Tip: for “missing dependency” tests, mark those components as `lazy=True` so
 
 ---
 
+## 🔌 Extensibility: Plugins, Binder, and Lifecycle Hooks
+
+From `v0.4.0` onward, Pico-IoC can be cleanly extended without patching the core.
+This enables optional integration layers like `pico-ioc-rest` for Flask, FastAPI, etc., while keeping the core dependency-free.
+
+### Plugin Protocol
+
+A plugin is any object that implements some or all of the following methods:
+
+```python
+from pico_ioc import PicoPlugin, Binder
+
+class MyPlugin:
+    def before_scan(self, package, binder: Binder): ...
+    def visit_class(self, module, cls, binder: Binder): ...
+    def after_scan(self, package, binder: Binder): ...
+    def after_bind(self, container, binder: Binder): ...
+    def before_eager(self, container, binder: Binder): ...
+    def after_ready(self, container, binder: Binder): ...
+```
+
+All hooks are optional. If present, they are called in this order during `init()`:
+
+1. **before\_scan** — called before package scanning starts.
+2. **visit\_class** — called for every class discovered during scanning.
+3. **after\_scan** — called after scanning all modules.
+4. **after\_bind** — called after the core has bound all components/factories.
+5. **before\_eager** — called right before eager (non-lazy) instantiation.
+6. **after\_ready** — called after all eager instantiation is complete.
+
+### Binder API
+
+Plugins receive a [`Binder`](#binder-api) instance in each hook, allowing them to:
+
+* **bind**: register new providers in the container.
+* **has**: check if a binding exists.
+* **get**: resolve a binding immediately.
+
+Example plugin that binds a “marker” component when a certain class is discovered:
+
+```python
+class MarkerPlugin:
+    def visit_class(self, module, cls, binder):
+        if cls.__name__ == "SpecialService" and not binder.has("marker"):
+            binder.bind("marker", lambda: {"ok": True}, lazy=False)
+
+container = init("my_app", plugins=(MarkerPlugin(),))
+assert container.get("marker") == {"ok": True}
+```
+
+### Creating Extensions
+
+With the plugin API, you can build separate packages like `pico-ioc-rest`:
+
+```python
+from pico_ioc import PicoPlugin, Binder, create_instance, resolve_param
+from flask import Flask
+
+class FlaskRestPlugin:
+    def __init__(self):
+        self.controllers = []
+
+    def visit_class(self, module, cls, binder: Binder):
+        if getattr(cls, "_is_controller", False):
+            self.controllers.append(cls)
+
+    def after_bind(self, container, binder: Binder):
+        app: Flask = container.get(Flask)
+        for ctl_cls in self.controllers:
+            ctl = create_instance(ctl_cls, container)
+            # register routes here using `resolve_param` for handler DI
+```
+
+### Public Helpers for Extensions
+
+Plugins can reuse Pico-IoC’s DI logic without duplicating it:
+
+* **`create_instance(cls, container)`** — instantiate a class with DI, respecting Pico-IoC’s resolution order.
+* **`resolve_param(container, parameter)`** — resolve a single function/class parameter via Pico-IoC rules.
+
+---
+
 ## ❓ FAQ
 
 **Q: Can I make the container lenient at startup?**

pico_ioc-0.4.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+pico_ioc/__init__.py,sha256=IqQOM75teE_gplSaemvxrfZjjj3w8-PBoRWRzFtZsz4,15219
+pico_ioc/_version.py,sha256=2eiWQI55fd-roDdkt4Hvl9WzrTJ4xQo33VzFud6D03U,22
+pico_ioc-0.4.0.dist-info/METADATA,sha256=vpgj38emsZxoJoGcW8-CWBt5K59U8cUF2GZrCzGy2ss,10733
+pico_ioc-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-0.4.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-0.4.0.dist-info/RECORD,,

pico_ioc-0.3.1.dist-info/RECORD

@@ -1,6 +0,0 @@
-pico_ioc/__init__.py,sha256=8VKuQM7hgXNrkPNMnpZ8ixg6LK4DpKCU-hvSSidGzEU,11874
-pico_ioc/_version.py,sha256=TZkGuMIRSRmUY3XCIs5owt2o60vXyqYMHWIkhx65uYE,22
-pico_ioc-0.3.1.dist-info/METADATA,sha256=oR-ft50RlnmX5BB_bFOoq5tIuaVflb3GTGXU9rI5oFM,7751
-pico_ioc-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-0.3.1.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-0.3.1.dist-info/RECORD,,