pico-ioc 0.3.1__tar.gz → 0.4.0__tar.gz

{pico_ioc-0.3.1 → pico_ioc-0.4.0}/PKG-INFO

@@ -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.3.1 → pico_ioc-0.4.0}/README.md

@@ -196,6 +196,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.3.1 → pico_ioc-0.4.0}/src/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-0.4.0/src/pico_ioc/_version.py

@@ -0,0 +1 @@
+__version__ = '0.4.0'

{pico_ioc-0.3.1 → pico_ioc-0.4.0}/src/pico_ioc.egg-info/PKG-INFO

@@ -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.3.1 → pico_ioc-0.4.0}/tests/test_pico_ioc.py

@@ -86,7 +86,7 @@ class ServiceFactory:
         CREATION_COUNTER["value"] += 1
         return "This is a complex service"
 
-    @provides(key="fast_model")  # eager by default; blueprint will instantiate once
+    @provides(key="fast_model")  # eager by default; instantiated once
     def create_fast_model(self):
         FAST_COUNTER["value"] += 1
         return {"who": "fast"}
@@ -106,7 +106,7 @@ import test_project
 from test_project.services.components import SimpleService
 
 ioc = pico_ioc.init(test_project)
-ioc.get(SimpleService)  # should raise RuntimeError due to re-entrant access during scan
+ioc.get(SimpleService)  # should raise during scan; import is caught/logged by scanner
 """
     )
 
@@ -121,7 +121,7 @@ ioc.get(SimpleService)  # should raise RuntimeError due to re-entrant access dur
         sys.modules.pop(m, None)
 
 
-# --- Test Suite ---
+# --- Core behavior tests ---
 
 def test_simple_component_retrieval(test_project):
     from test_project.services.components import SimpleService
@@ -193,7 +193,7 @@ def test_resolution_prefers_name_over_type(test_project):
     container = pico_ioc.init(test_project)
     comp = container.get(NeedsNameVsType)
     assert comp.model == {"who": "fast"}
-    assert FAST_COUNTER["value"] == 1  # created once by blueprint
+    assert FAST_COUNTER["value"] == 1  # created once by factory
     assert BASE_COUNTER["value"] == 0  # still lazy
 
 
@@ -218,7 +218,6 @@ def test_resolution_fallback_to_type_mro(test_project):
 def test_missing_dependency_raises_clear_error(test_project):
     from test_project.services.components import MissingDep
     container = pico_ioc.init(test_project)
-
     proxy = container.get(MissingDep)  # returns ComponentProxy
     with pytest.raises(NameError, match="No provider found for key"):
         _ = bool(proxy)
@@ -227,6 +226,7 @@ def test_missing_dependency_raises_clear_error(test_project):
 def test_reentrant_access_is_blocked_and_container_still_initializes(test_project, caplog):
     caplog.set_level(logging.INFO)
     container = pico_ioc.init(test_project)
+    # The scanner logs a warning including the RuntimeError text thrown by get()
     assert any(
         "re-entrant container access during scan" in rec.message
         for rec in caplog.records
@@ -235,3 +235,43 @@ def test_reentrant_access_is_blocked_and_container_still_initializes(test_projec
     svc = container.get(SimpleService)
     assert isinstance(svc, SimpleService)
 
+
+# --- Plugin & Binder smoke test ---
+
+def test_plugin_hooks_and_binder(test_project):
+    """
+    Verifies that a plugin can observe classes during scan, bind a value via Binder,
+    and see lifecycle hooks firing in order.
+    """
+    calls = []
+
+    class MyPlugin:
+        def before_scan(self, package, binder):
+            calls.append("before_scan")
+
+        def visit_class(self, module, cls, binder):
+            # As an example, bind a marker when we see a specific class name
+            if cls.__name__ == "SimpleService" and not binder.has("marker"):
+                binder.bind("marker", lambda: {"ok": True}, lazy=False)
+
+        def after_scan(self, package, binder):
+            calls.append("after_scan")
+
+        def after_bind(self, container, binder):
+            calls.append("after_bind")
+
+        def before_eager(self, container, binder):
+            calls.append("before_eager")
+
+        def after_ready(self, container, binder):
+            calls.append("after_ready")
+
+    container = pico_ioc.init(test_project, plugins=(MyPlugin(),))
+
+    # Order is not strictly enforced between middle hooks, but all should be present.
+    for expected in ["before_scan", "after_scan", "after_bind", "before_eager", "after_ready"]:
+        assert expected in calls
+
+    # Marker bound by plugin should be retrievable
+    assert container.get("marker") == {"ok": True}
+

pico_ioc-0.3.1/src/pico_ioc/_version.py

@@ -1 +0,0 @@
-__version__ = '0.3.1'