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

pico_ioc/__init__.py

@@ -186,18 +186,43 @@ def resolve_param(container: PicoContainer, p: inspect.Parameter) -> Any:
     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 = {}
+    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):
+            if p.name == 'self' or p.kind in (
+                inspect.Parameter.VAR_POSITIONAL,
+                inspect.Parameter.VAR_KEYWORD,
+            ):
                 continue
-            deps[p.name] = resolve_param(container, p)
+
+            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: ...
@@ -217,12 +242,14 @@ def _scan_and_configure(
     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):
@@ -243,40 +270,84 @@ def _scan_and_configure(
                     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__)
-            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'):
-                    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)
         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(
@@ -335,29 +406,3 @@ def init(
     logging.info("Container configured and ready.")
     return _container
 
-
-
-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
-

pico_ioc/_version.py

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

pico_ioc-0.5.1.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 0.5.1
+Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Pérez Cabrera
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+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
+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/)
+[![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)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-ioc/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-ioc)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+
+**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 order** — **parameter name** takes precedence over **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 (Updated in v0.5.0)
+
+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)**
+
+This means that if a dependency could match both by name and type, **the name match wins**.
+
+Example:
+
+```python
+from pico_ioc import component, factory_component, provides, init
+
+class BaseType: ...
+class Impl(BaseType): ...
+
+@component(name="inject_by_name")
+class InjectByName:
+    def __init__(self):
+        self.value = "by-name"
+
+@factory_component
+class NameVsTypeFactory:
+    @provides("choose", lazy=True)
+    def make(self, inject_by_name, hint: BaseType = None):
+        return inject_by_name.value
+
+container = init(__name__)
+assert container.get("choose") == "by-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     │
+       └───────────────────────┘
+```
+
+---
+
+## 🛠 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
+```
+
+**New in v0.5.0:**
+Additional tests verify:
+
+* Name vs. type precedence.
+* Mixed binding key resolution in factories.
+* Eager vs. lazy instantiation edge cases.
+
+---
+
+## 🔌 Extensibility: Plugins, Binder, and Lifecycle Hooks
+
+From `v0.4.0` onward, Pico-IoC can be cleanly extended without patching the core.
+
+*(plugin API docs unchanged from before)*
+
+---
+
+## 📜 License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
+
+```
+
+

pico_ioc-0.5.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+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,,

pico_ioc-0.5.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Pérez Cabrera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pico_ioc-0.4.0.dist-info/METADATA

@@ -1,321 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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,,