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

pico_ioc/__init__.py

@@ -1,63 +1,96 @@
-import functools, inspect, pkgutil, importlib, logging
-from typing import Callable, Any, Optional
+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:
-    # written at build time by setuptools-scm
     from ._version import __version__
-except Exception:  # pragma: no cover
+except Exception:
     __version__ = "0.0.0"
 
-__all__ = ["__version__"]
+__all__ = [
+    "__version__",
+    "PicoContainer",
+    "Binder",
+    "PicoPlugin",
+    "init",
+    "component",
+    "factory_component",
+    "provides",
+    "resolve_param",
+    "create_instance",
+]
 
-# ------------------------------------------------------------------------------
-# Re-entrancy guards
-# ------------------------------------------------------------------------------
-# True while init/scan is running. Blocks userland container access during scan.
 _scanning: ContextVar[bool] = ContextVar("pico_scanning", default=False)
-
-# True while the container is resolving deps for a component (internal use allowed).
 _resolving: ContextVar[bool] = ContextVar("pico_resolving", default=False)
 
-# ==============================================================================
-# --- 1. Container and Chameleon Proxy (Framework-Agnostic) ---
-# ==============================================================================
 class PicoContainer:
     def __init__(self):
-        self._providers: dict[Any, Callable[[], Any]] = {}
-        self._singletons: dict[Any, Any] = {}
+        self._providers: Dict[Any, Dict[str, Any]] = {}
+        self._singletons: Dict[Any, Any] = {}
 
-    def bind(self, key: Any, provider: Callable[[], Any]):
-        self._providers[key] = provider
+    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:
-        # Forbid user code calling container.get() while the scanner is importing modules.
-        # Allow only internal calls performed during dependency resolution.
         if _scanning.get() and not _resolving.get():
-            raise RuntimeError(
-                "pico-ioc: re-entrant container access during scan. "
-                "Avoid calling init()/get() at import time (e.g., in a module body). "
-                "Move resolution to runtime (e.g., under if __name__ == '__main__':) "
-                "or delay it until pico-ioc init completes."
-            )
-
+            raise RuntimeError("pico-ioc: re-entrant container access during scan.")
         if key in self._singletons:
             return self._singletons[key]
-        if key in self._providers:
-            instance = self._providers[key]()
-            self._singletons[key] = instance
-            return instance
-        raise NameError(f"No provider found for key: {key}")
-
-class LazyProxy:
-    """
-    A full-fledged lazy proxy that delegates almost all operations
-    to the real object, which is created only on first access.
-    It is completely framework-agnostic.
-    """
+        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)
@@ -69,30 +102,16 @@ class LazyProxy:
             object.__setattr__(self, "__real_object", real_obj)
         return real_obj
 
-    # --- Core Proxying and Representation ---
     @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())
-
-    # --- Emulation of container types ---
+    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
@@ -100,8 +119,6 @@ class LazyProxy:
     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()
-
-    # --- Emulation of numeric types and operators ---
     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
@@ -116,8 +133,6 @@ class LazyProxy:
     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
-
-    # --- Right-hand side numeric operators ---
     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()
@@ -132,14 +147,10 @@ class LazyProxy:
     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()
-
-    # --- Unary operators ---
     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()
-
-    # --- Comparison operators ---
     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
@@ -147,31 +158,19 @@ class LazyProxy:
     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())
-
-    # --- Truthiness, Callability and Context Management ---
     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)
 
-# ==============================================================================
-# --- 2. The Scanner and `init` Facade ---
-# ==============================================================================
-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")
-
-    # 1) NAME
     if container.has(p.name):
         return container.get(p.name)
-
     ann = p.annotation
-
-    # 2) TYPE
     if ann is not inspect._empty and container.has(ann):
         return container.get(ann)
-
-    # 3) TYPE MRO
     if ann is not inspect._empty:
         try:
             for base in getattr(ann, "__mro__", ())[1:]:
@@ -181,80 +180,115 @@ def _resolve_param(container: PicoContainer, p: inspect.Parameter) -> Any:
                     return container.get(base)
         except Exception:
             pass
-
-    # 4) str(NAME)
     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:
+    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
+    *,
+    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__}'...")
+    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)")
+            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}")
-
-    # Register factories
+            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__)
             instance = factory_cls(container) if 'container' in sig.parameters else factory_cls()
             for _, method in inspect.getmembers(instance, inspect.ismethod):
                 if hasattr(method, '_provides_name'):
-                    container.bind(getattr(method, '_provides_name'), method)
-        except Exception as e:
-            logging.error(f"  ❌ Error in factory {factory_cls.__name__}: {e}", exc_info=True)
-
-    # Register components
+                    key = getattr(method, '_provides_name')
+                    is_lazy = bool(getattr(method, '_pico_lazy', False))
+                    def make_provider(m=method, lazy=is_lazy):
+                        def _factory():
+                            if lazy:
+                                return ComponentProxy(lambda: m())
+                            return m()
+                        return _factory
+                    container.bind(key, make_provider(), lazy=is_lazy)
+        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)
-
-        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)
-
-        container.bind(key, create_component)
-
-_container = None
-
-def init(root_package, *, exclude: Optional[Callable[[str], bool]] = None, auto_exclude_caller: bool = True):
-    """
-    Initialize the global container and scan the given root package/module.
-    While scanning, re-entrant userland access to container.get() is blocked
-    to avoid import-time side effects.
-    """
+        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)
+
+_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:
@@ -263,7 +297,6 @@ def init(root_package, *, exclude: Optional[Callable[[str], bool]] = None, auto_
             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):
@@ -272,47 +305,59 @@ def init(root_package, *, exclude: Optional[Callable[[str], bool]] = None, auto_
                 prev = combined_exclude
                 def combined_exclude(mod: str, _caller=caller_name, _prev=prev):
                     return mod == _caller or _prev(mod)
-
     _container = PicoContainer()
-    logging.info("🔌 Initializing 'pico-ioc'...")
-
+    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)
-
-    logging.info("✅ Container configured and ready.")
+    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
 
-# ==============================================================================
-# --- 3. The Decorators ---
-# ==============================================================================
+
+
 def factory_component(cls):
     setattr(cls, '_is_factory_component', True)
     return cls
 
-def provides(key: Any, *, lazy: bool = True):
-    """
-    Declare that a factory method provides a component under 'key'.
-    By default, returns a LazyProxy that instantiates upon first real use.
-    """
+
+def provides(key: Any, *, lazy: bool = False):
     def decorator(func):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
-            return LazyProxy(lambda: func(*args, **kwargs)) if lazy else func(*args, **kwargs)
-        setattr(wrapper, '_provides_name', key)  # legacy-compatible storage
+            return func(*args, **kwargs)
+        setattr(wrapper, '_provides_name', key)
+        setattr(wrapper, '_pico_lazy', bool(lazy))
         return wrapper
     return decorator
 
-def component(cls=None, *, name: str = None):
-    """
-    Mark a class as a component. Registered by class type by default,
-    or by 'name' if provided.
-    """
+
+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
 

pico_ioc/_version.py

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

pico_ioc-0.4.0.dist-info/METADATA

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+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
+Project-URL: Repository, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-ioc/issues
+Keywords: ioc,di,dependency injection,inversion of control,decorator
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/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/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-ioc/actions/workflows/ci.yml/badge.svg)
+
+**Pico-IoC** is a tiny, zero-dependency, decorator-based Inversion of Control container for Python.
+Build loosely-coupled, testable apps without manual wiring. Inspired by the Spring ecosystem.
+
+---
+
+## ✨ Key Features
+
+* **Zero dependencies** — pure Python.
+* **Decorator API** — `@component`, `@factory_component`, `@provides`.
+* **Auto discovery** — scans a package and registers components.
+* **Eager by default, fail-fast** — non-lazy bindings are instantiated immediately after `init()`. Missing deps fail startup.
+* **Opt-in lazy** — set `lazy=True` to defer creation (wrapped in `ComponentProxy`).
+* **Factories** — encapsulate complex creation logic.
+* **Smart resolution** — by **parameter name**, then **type annotation**, then **MRO fallback**, then **string(name)**.
+* **Re-entrancy guard** — prevents `get()` during scanning.
+* **Auto-exclude caller** — `init()` skips the calling module to avoid double scanning.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pico-ioc
+```
+
+---
+
+## 🚀 Quick Start
+
+```python
+from pico_ioc import component, init
+
+@component
+class AppConfig:
+    def get_db_url(self):
+        return "postgresql://user:pass@host/db"
+
+@component
+class DatabaseService:
+    def __init__(self, config: AppConfig):
+        self._cs = config.get_db_url()
+    def get_data(self):
+        return f"Data from {self._cs}"
+
+container = init(__name__)  # blueprint runs here (eager + fail-fast)
+db = container.get(DatabaseService)
+print(db.get_data())
+```
+
+---
+
+## 🧩 Custom Component Keys
+
+```python
+from pico_ioc import component, init
+
+@component(name="config")  # custom key
+class AppConfig:
+    db_url = "postgresql://user:pass@localhost/db"
+
+@component
+class Repository:
+    def __init__(self, config: "config"):  # resolve by NAME
+        self.url = config.db_url
+
+container = init(__name__)
+print(container.get("config").db_url)
+```
+
+---
+
+## 🏭 Factories and `@provides`
+
+* Default is **eager** (`lazy=False`). Eager bindings are constructed at the end of `init()`.
+* Use `lazy=True` for on-first-use creation via `ComponentProxy`.
+
+```python
+from pico_ioc import factory_component, provides, init
+
+COUNTER = {"value": 0}
+
+@factory_component
+class ServicesFactory:
+    @provides(key="heavy_service", lazy=True)
+    def heavy(self):
+        COUNTER["value"] += 1
+        return {"payload": "hello"}
+
+container = init(__name__)
+svc = container.get("heavy_service")  # not created yet
+print(COUNTER["value"])               # 0
+print(svc["payload"])                 # triggers creation
+print(COUNTER["value"])               # 1
+```
+
+---
+
+## 🧠 Dependency Resolution Order
+
+1. parameter **name**
+2. exact **type annotation**
+3. **MRO fallback** (walk base classes)
+4. `str(name)`
+
+---
+
+## ⚡ Eager vs. Lazy (Blueprint Behavior)
+
+At the end of `init()`, Pico-IoC performs a **blueprint**:
+
+- **Eager** (`lazy=False`, default): instantiated immediately; failures stop startup.
+- **Lazy** (`lazy=True`): returns a `ComponentProxy`; instantiated on first real use.
+
+**Lifecycle:**
+
+           ┌───────────────────────┐
+           │        init()         │
+           └───────────────────────┘
+                      │
+                      ▼
+           ┌───────────────────────┐
+           │   Scan & bind deps    │
+           └───────────────────────┘
+                      │
+                      ▼
+           ┌─────────────────────────────┐
+           │  Blueprint instantiates all │
+           │    non-lazy (eager) beans   │
+           └─────────────────────────────┘
+                      │
+           ┌───────────────────────┐
+           │   Container ready     │
+           └───────────────────────┘
+
+
+**Best practice:** keep eager+fail-fast for production parity with Spring; use lazy only for heavy/optional deps or to support negative tests.
+
+---
+
+## 🔄 Migration Guide (v0.2.1 → v0.3.0)
+
+* **Defaults changed:** `@component` and `@provides` now default to `lazy=False` (eager).
+* **Proxy renamed:** `LazyProxy` → `ComponentProxy` (only relevant if referenced directly).
+* **Tests/fixtures:** components intentionally missing deps should be marked `@component(lazy=True)` (to avoid failing `init()`), or excluded from the scan.
+
+Example fix for an intentional failure case:
+
+```python
+@component(lazy=True)
+class MissingDep:
+    def __init__(self, missing):
+        self.missing = missing
+```
+
+---
+
+## 🛠 API Reference
+
+### `init(root, *, exclude=None, auto_exclude_caller=True) -> PicoContainer`
+
+Scan and bind components in `root` (str module name or module).
+Skips the calling module if `auto_exclude_caller=True`.
+Runs blueprint (instantiate all `lazy=False` bindings).
+
+### `@component(cls=None, *, name=None, lazy=False)`
+
+Register a class as a component.
+Use `name` for a custom key.
+Set `lazy=True` to defer creation.
+
+### `@factory_component`
+
+Mark a class as a component factory (its methods can `@provides` bindings).
+
+### `@provides(key, *, lazy=False)`
+
+Declare that a factory method provides a component under `key`.
+Set `lazy=True` for deferred creation (`ComponentProxy`).
+
+---
+
+## 🧪 Testing
+
+```bash
+pip install tox
+tox -e py311
+```
+
+Tip: for “missing dependency” tests, mark those components as `lazy=True` so `init()` remains fail-fast for real components while your test still asserts failure on resolution.
+
+---
+
+## 🔌 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?**
+A: By design it’s strict. Prefer `lazy=True` on specific bindings or exclude problem modules from the scan.
+
+**Q: Thread safety?**
+A: Container uses `ContextVar` to guard re-entrancy during scanning. Singletons are created once per container; typical usage is in single-threaded app startup, then read-mostly.
+
+**Q: Frameworks?**
+A: Framework-agnostic. Works with Flask, FastAPI, CLIs, scripts, etc.
+
+---
+
+## 📜 License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
+
+

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.0.dist-info/METADATA

@@ -1,228 +0,0 @@
-Metadata-Version: 2.4
-Name: pico-ioc
-Version: 0.3.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
-Project-URL: Repository, https://github.com/dperezcabrera/pico-ioc
-Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-ioc/issues
-Keywords: ioc,di,dependency injection,inversion of control,decorator
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/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/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-![CI (tox matrix)](https://github.com/dperezcabrera/pico-ioc/actions/workflows/ci.yml/badge.svg)
-
-**Pico-IoC** is a tiny, zero-dependency, decorator-based Inversion of Control (IoC) container for Python.
-It helps you manage dependencies in a clean, intuitive, and *Pythonic* way.
-
-The core idea is to let you build loosely coupled, easily testable applications without manually wiring components.
-*Inspired by the IoC philosophy popularized by the Spring Framework.*
-
----
-
-## ✨ Key Features
-
-* **Zero Dependencies:** Pure Python, no external libraries.
-* **Decorator-Based API:** Simple decorators like `@component` and `@provides`.
-* **Automatic Discovery:** Scans your package to auto-register components.
-* **Lazy Instantiation:** Objects are created on first use.
-* **Flexible Factories:** Encapsulate complex creation logic.
-* **Framework-Agnostic:** Works with Flask, FastAPI, CLIs, scripts, etc.
-* **Smart Dependency Resolution:** Resolves by **parameter name**, then **type annotation**, then **MRO fallback**.
-* **Auto-Exclude Caller:** `init()` automatically skips the calling module to avoid double-initialization during scans.
-
----
-
-## 📦 Installation
-
-```bash
-pip install pico-ioc
-```
-
----
-
-## 🚀 Quick Start
-
-```python
-from pico_ioc import component, init
-
-@component
-class AppConfig:
-    def get_db_url(self):
-        return "postgresql://user:pass@host/db"
-
-@component
-class DatabaseService:
-    def __init__(self, config: AppConfig):
-        self._cs = config.get_db_url()
-
-    def get_data(self):
-        return f"Data from {self._cs}"
-
-# Initialize the container scanning the current module
-container = init(__name__)
-
-db = container.get(DatabaseService)
-print(db.get_data())  # Data from postgresql://user:pass@host/db
-```
-
----
-
-## 🧩 Custom Component Keys
-
-You can register a component with a **custom key** (string, class, enum…).
-`key=` is the preferred syntax. For backwards compatibility, `name=` still works.
-
-```python
-from pico_ioc import component, init
-
-@component(name="config")  # still supported for legacy code
-class AppConfig:
-    def __init__(self):
-        self.db_url = "postgresql://user:pass@localhost/db"
-
-@component
-class Repository:
-    def __init__(self, config: "config"):  # resolve by name
-        self._url = config.db_url
-
-container = init(__name__)
-repo = container.get(Repository)
-print(repo._url)           # postgresql://user:pass@localhost/db
-print(container.get("config").db_url)
-```
-
----
-
-## 🏭 Factory Components and `@provides`
-
-Factories can provide components under a specific **key**.
-Default is lazy creation (via `LazyProxy`).
-
-```python
-from pico_ioc import factory_component, provides, init
-
-CREATION_COUNTER = {"value": 0}
-
-@factory_component
-class ServicesFactory:
-    @provides(key="heavy_service")  # preferred
-    def make_heavy(self):
-        CREATION_COUNTER["value"] += 1
-        return {"payload": "Hello from heavy service"}
-
-container = init(__name__)
-svc = container.get("heavy_service")
-print(CREATION_COUNTER["value"])  # 0 (not created yet)
-
-print(svc["payload"])             # triggers creation
-print(CREATION_COUNTER["value"])  # 1
-```
-
----
-
-## 📦 Project-Style Scanning
-
-```
-project_root/
-└── myapp/
-    ├── __init__.py
-    ├── services.py
-    └── main.py
-```
-
-**myapp/services.py**
-
-```python
-from pico_ioc import component
-
-@component
-class Config:
-    def __init__(self):
-        self.base_url = "https://api.example.com"
-
-@component
-class ApiClient:
-    def __init__(self, config: Config):
-        self.base_url = config.base_url
-
-    def get(self, path: str):
-        return f"GET {self.base_url}/{path}"
-```
-
-**myapp/main.py**
-
-```python
-import pico_ioc
-from myapp.services import ApiClient
-
-container = pico_ioc.init("myapp")
-client = container.get(ApiClient)
-print(client.get("status"))  # GET https://api.example.com/status
-```
-
----
-
-## 🧠 Dependency Resolution Order
-
-When Pico-IoC instantiates a component, it tries to resolve each parameter in this order:
-
-1. **Exact parameter name** (string key in container)
-2. **Exact type annotation** (class key in container)
-3. **MRO fallback** (walk base classes until match)
-4. **String version** of the parameter name
-
----
-
-## 🛠 API Reference
-
-### `init(root_package_or_module, *, exclude=None, auto_exclude_caller=True) -> PicoContainer`
-
-Scan the given root **package** (str) or **module**.
-By default, excludes the calling module.
-
-### `@component(cls=None, *, name=None)`
-
-Register a class as a component.
-If `name` is given, registers under that string; otherwise under the class type.
-
-### `@factory_component`
-
-Register a class as a factory of components.
-
-### `@provides(key=None, *, name=None, lazy=True)`
-
-Declare that a factory method provides a component under `key`.
-`name` is accepted for backwards compatibility.
-If `lazy=True`, returns a `LazyProxy` that instantiates on first real use.
-
----
-
-## 🧪 Testing
-
-```bash
-pip install tox
-tox -e py311
-```
-
----
-
-## 📜 License
-
-MIT — see [LICENSE](https://opensource.org/licenses/MIT)

pico_ioc-0.3.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-pico_ioc/__init__.py,sha256=wCgi07l_0ZqhgZRfoRgWld_Q3_0qkqazUPWsO0XbPQI,13474
-pico_ioc/_version.py,sha256=3wVEs2QD_7OcTlD97cZdCeizd2hUbJJ0GeIO8wQIjrk,22
-pico_ioc-0.3.0.dist-info/METADATA,sha256=nzmDf0ZLTn0OkaoYDytJDnPQstVgVf2ExGZv0nMs15g,6374
-pico_ioc-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-0.3.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-0.3.0.dist-info/RECORD,,