PyPI - pico-ioc - Versions diffs - 0.1.1__tar.gz → 0.2.0__tar.gz - Mend

pico-ioc 0.1.1tar.gz → 0.2.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

{pico_ioc-0.1.1 → pico_ioc-0.2.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 0.1.1
+Version: 0.2.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
@@ -21,32 +21,35 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-# Pico-IoC: A Minimalist IoC Container for Python
+# 📦 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.
+**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.
+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
+## ✨ 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.
+* **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
+## 📦 Installation
 ```bash
 pip install pico-ioc
@@ -54,9 +57,7 @@ pip install pico-ioc
 ---
-## Quick Start
-Getting started is simple. Decorate your classes and let Pico-IoC wire them up.
+## 🚀 Quick Start
 ```python
 from pico_ioc import component, init
@@ -83,21 +84,22 @@ print(db.get_data())  # Data from postgresql://user:pass@host/db
 ---
-## More Examples
+## 🧩 Custom Component Keys
-### 🧩 Custom Component Name
+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")
+@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"):  # refer by custom name if you prefer
+    def __init__(self, config: "config"):  # resolve by name
         self._url = config.db_url
 container = init(__name__)
@@ -106,9 +108,12 @@ print(repo._url)           # postgresql://user:pass@localhost/db
 print(container.get("config").db_url)
 ```
-> Pico-IoC prefers **type annotations** to resolve deps; if missing, it falls back to the **parameter name**.
+---
-### 💤 Lazy Factories (only build when used)
+## 🏭 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
@@ -117,7 +122,7 @@ CREATION_COUNTER = {"value": 0}
 @factory_component
 class ServicesFactory:
-    @provides(name="heavy_service")  # returns a LazyProxy by default
+    @provides(key="heavy_service")  # preferred
     def make_heavy(self):
         CREATION_COUNTER["value"] += 1
         return {"payload": "Hello from heavy service"}
@@ -130,7 +135,9 @@ print(svc["payload"])             # triggers creation
 print(CREATION_COUNTER["value"])  # 1
 ```
-### 📦 Project-Style Package Scanning
+---
+## 📦 Project-Style Scanning
 ```
 project_root/
@@ -165,61 +172,62 @@ class ApiClient:
 import pico_ioc
 from myapp.services import ApiClient
-# Scan the whole 'myapp' package
 container = pico_ioc.init("myapp")
 client = container.get(ApiClient)
 print(client.get("status"))  # GET https://api.example.com/status
 ```
 ---
-## API Reference (mini)
+## 🧠 Dependency Resolution Order
-### `init(root_package_or_module) -> PicoContainer`
+When Pico-IoC instantiates a component, it tries to resolve each parameter in this order:
-Initialize the container by scanning a root **package** (str) or **module**. Returns the configured container.
+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
-### `@component(cls=None, *, name: str | None = None)`
+---
-Mark a class as a component. Registered by **class type** by default, or by **name** if provided.
+## 🛠 API Reference
-### `@factory_component`
+### `init(root_package_or_module, *, exclude=None, auto_exclude_caller=True) -> PicoContainer`
-Mark a class as a factory holder. Methods inside can be `@provides(...)`.
+Scan the given root **package** (str) or **module**.
+By default, excludes the calling module.
-### `@provides(name: str, lazy: bool = True)`
+### `@component(cls=None, *, name=None)`
-Declare that a factory method **produces** a component registered under `name`. By default it’s **lazy** (a proxy that creates on first real use).
+Register a class as a component.
+If `name` is given, registers under that string; otherwise under the class type.
----
+### `@factory_component`
-## Testing
+Register a class as a factory of components.
-`pico-ioc` ships with `pytest` tests and a `tox` matrix.
+### `@provides(key=None, *, name=None, lazy=True)`
-```bash
-pip install tox
-tox -e py311           # run on a specific version
-tox                    # run all configured envs
-```
+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.
 ---
-## Contributing
+## 🧪 Testing
-Issues and PRs are welcome. If you spot a bug or have an idea, open an issue!
+```bash
+pip install tox
+tox -e py311
+```
 ---
-## License
+## 📜 License
-MIT — see the [LICENSE](https://opensource.org/licenses/MIT).
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
 ---
-## Authors
+¿Quieres que también te prepare **un ejemplo completo en el README** con `fast_model` y `BaseChatModel` para que quede documentado el nuevo orden de resolución? Así quedaría clarísimo para cualquiera que lo use.
-* **David Perez Cabrera**
-* **Gemini 2.5-Pro**
-* **GPT-5**

{pico_ioc-0.1.1 → pico_ioc-0.2.0}/README.md RENAMED Viewed

@@ -1,29 +1,32 @@
-# Pico-IoC: A Minimalist IoC Container for Python
+# 📦 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.
+**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.
+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
+## ✨ 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.
+* **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
+## 📦 Installation
 ```bash
 pip install pico-ioc
@@ -31,9 +34,7 @@ pip install pico-ioc
 ---
-## Quick Start
-Getting started is simple. Decorate your classes and let Pico-IoC wire them up.
+## 🚀 Quick Start
 ```python
 from pico_ioc import component, init
@@ -60,21 +61,22 @@ print(db.get_data())  # Data from postgresql://user:pass@host/db
 ---
-## More Examples
+## 🧩 Custom Component Keys
-### 🧩 Custom Component Name
+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")
+@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"):  # refer by custom name if you prefer
+    def __init__(self, config: "config"):  # resolve by name
         self._url = config.db_url
 container = init(__name__)
@@ -83,9 +85,12 @@ print(repo._url)           # postgresql://user:pass@localhost/db
 print(container.get("config").db_url)
 ```
-> Pico-IoC prefers **type annotations** to resolve deps; if missing, it falls back to the **parameter name**.
+---
-### 💤 Lazy Factories (only build when used)
+## 🏭 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
@@ -94,7 +99,7 @@ CREATION_COUNTER = {"value": 0}
 @factory_component
 class ServicesFactory:
-    @provides(name="heavy_service")  # returns a LazyProxy by default
+    @provides(key="heavy_service")  # preferred
     def make_heavy(self):
         CREATION_COUNTER["value"] += 1
         return {"payload": "Hello from heavy service"}
@@ -107,7 +112,9 @@ print(svc["payload"])             # triggers creation
 print(CREATION_COUNTER["value"])  # 1
 ```
-### 📦 Project-Style Package Scanning
+---
+## 📦 Project-Style Scanning
 ```
 project_root/
@@ -142,61 +149,62 @@ class ApiClient:
 import pico_ioc
 from myapp.services import ApiClient
-# Scan the whole 'myapp' package
 container = pico_ioc.init("myapp")
 client = container.get(ApiClient)
 print(client.get("status"))  # GET https://api.example.com/status
 ```
 ---
-## API Reference (mini)
+## 🧠 Dependency Resolution Order
-### `init(root_package_or_module) -> PicoContainer`
+When Pico-IoC instantiates a component, it tries to resolve each parameter in this order:
-Initialize the container by scanning a root **package** (str) or **module**. Returns the configured container.
+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
-### `@component(cls=None, *, name: str | None = None)`
+---
-Mark a class as a component. Registered by **class type** by default, or by **name** if provided.
+## 🛠 API Reference
-### `@factory_component`
+### `init(root_package_or_module, *, exclude=None, auto_exclude_caller=True) -> PicoContainer`
-Mark a class as a factory holder. Methods inside can be `@provides(...)`.
+Scan the given root **package** (str) or **module**.
+By default, excludes the calling module.
-### `@provides(name: str, lazy: bool = True)`
+### `@component(cls=None, *, name=None)`
-Declare that a factory method **produces** a component registered under `name`. By default it’s **lazy** (a proxy that creates on first real use).
+Register a class as a component.
+If `name` is given, registers under that string; otherwise under the class type.
----
+### `@factory_component`
-## Testing
+Register a class as a factory of components.
-`pico-ioc` ships with `pytest` tests and a `tox` matrix.
+### `@provides(key=None, *, name=None, lazy=True)`
-```bash
-pip install tox
-tox -e py311           # run on a specific version
-tox                    # run all configured envs
-```
+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.
 ---
-## Contributing
+## 🧪 Testing
-Issues and PRs are welcome. If you spot a bug or have an idea, open an issue!
+```bash
+pip install tox
+tox -e py311
+```
 ---
-## License
+## 📜 License
-MIT — see the [LICENSE](https://opensource.org/licenses/MIT).
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
 ---
-## Authors
+¿Quieres que también te prepare **un ejemplo completo en el README** con `fast_model` y `BaseChatModel` para que quede documentado el nuevo orden de resolución? Así quedaría clarísimo para cualquiera que lo use.
-* **David Perez Cabrera**
-* **Gemini 2.5-Pro**
-* **GPT-5**

{pico_ioc-0.1.1 → pico_ioc-0.2.0}/src/pico_ioc/__init__.py RENAMED Viewed

@@ -1,7 +1,7 @@
 # src/pico_ioc/__init__.py
 import functools, inspect, pkgutil, importlib, logging, sys
-from typing import Callable, Any, Iterator, AsyncIterator
+from typing import Callable, Any, Iterator, Optional, AsyncIterator
 try:
     # written at build time by setuptools-scm
@@ -16,12 +16,15 @@ __all__ = ["__version__"]
 # ==============================================================================
 class PicoContainer:
     def __init__(self):
-        self._providers = {}
-        self._singletons = {}
+        self._providers: dict[Any, Callable[[], Any]] = {}
+        self._singletons: dict[Any, Any] = {}
     def bind(self, key: Any, provider: Callable[[], Any]):
         self._providers[key] = provider
+    def has(self, key: Any) -> bool:
+        return key in self._providers or key in self._singletons
     def get(self, key: Any) -> Any:
         if key in self._singletons:
             return self._singletons[key]
@@ -136,11 +139,47 @@ class LazyProxy:
 # ==============================================================================
 # --- 2. The Scanner and `init` Facade ---
 # ==============================================================================
-def _scan_and_configure(package_or_name, container: PicoContainer):
+def _resolve_param(container: PicoContainer, p: inspect.Parameter) -> Any:
+    if p.name == 'self' or p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+        raise RuntimeError("Invalid param for resolution")
+    if container.has(p.name):
+        return container.get(p.name)
+    ann = p.annotation
+    if ann is not inspect._empty and container.has(ann):
+        return container.get(ann)
+    if ann is not inspect._empty:
+        try:
+            for base in getattr(ann, "__mro__", ())[1:]:
+                if base is object:
+                    break
+                if container.has(base):
+                    return container.get(base)
+        except Exception:
+            pass
+    if container.has(str(p.name)):
+        return container.get(str(p.name))
+    key = p.name if not (ann and ann is not inspect._empty) else ann
+    return container.get(key)
+def _scan_and_configure(
+    package_or_name,
+    container: PicoContainer,
+    exclude: Optional[Callable[[str], bool]] = None
+):
     package = importlib.import_module(package_or_name) if isinstance(package_or_name, str) else package_or_name
     logging.info(f"🚀 Scanning in '{package.__name__}'...")
     component_classes, factory_classes = [], []
     for _, name, _ in pkgutil.walk_packages(package.__path__, package.__name__ + '.'):
+        # Skip excluded modules (used by auto_exclude_caller and custom excludes)
+        if exclude and exclude(name):
+            logging.info(f"  ⏭️ Skipping module {name} (excluded)")
+            continue
         try:
             module = importlib.import_module(name)
             for _, obj in inspect.getmembers(module, inspect.isclass):
@@ -167,24 +206,41 @@ def _scan_and_configure(package_or_name, container: PicoContainer):
             sig = inspect.signature(cls.__init__)
             deps = {}
             for p in sig.parameters.values():
-                if p.name == 'self' or p.kind in (
-                    inspect.Parameter.VAR_POSITIONAL,  # *args
-                    inspect.Parameter.VAR_KEYWORD,     # **kwargs
-                ):
+                if p.name == 'self' or p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
                     continue
-                dep_key = p.annotation if p.annotation is not inspect._empty else p.name
-                deps[p.name] = container.get(dep_key)
+                deps[p.name] = _resolve_param(container, p)
             return cls(**deps)
         container.bind(key, create_component)
 _container = None
-def init(root_package):
+def init(root_package, *, exclude: Optional[Callable[[str], bool]] = None, auto_exclude_caller: bool = True):
     global _container
     if _container:
         return _container
+    combined_exclude = exclude
+    if auto_exclude_caller:
+        # módulo que invoca a init()
+        try:
+            caller_frame = inspect.stack()[1].frame
+            caller_module = inspect.getmodule(caller_frame)
+            caller_name = getattr(caller_module, "__name__", None)
+        except Exception:
+            caller_name = None
+        if caller_name:
+            if combined_exclude is None:
+                def combined_exclude(mod: str, _caller=caller_name):
+                    return mod == _caller
+            else:
+                prev = combined_exclude
+                def combined_exclude(mod: str, _caller=caller_name, _prev=prev):
+                    return mod == _caller or _prev(mod)
     _container = PicoContainer()
     logging.info("🔌 Initializing 'pico-ioc'...")
-    _scan_and_configure(root_package, _container)
+    _scan_and_configure(root_package, _container, exclude=combined_exclude)
     logging.info("✅ Container configured and ready.")
     return _container
@@ -195,12 +251,13 @@ def factory_component(cls):
     setattr(cls, '_is_factory_component', True)
     return cls
-def provides(name: str, lazy: bool = True):
+def provides(key: Any, *, lazy: bool = True):
     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', name)
+        # mantenemos compat con _provides_name (por si alguien lo usa)
+        setattr(wrapper, '_provides_name', key)
         return wrapper
     return decorator

pico_ioc-0.2.0/src/pico_ioc/_version.py ADDED Viewed

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

{pico_ioc-0.1.1 → pico_ioc-0.2.0}/src/pico_ioc.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 0.1.1
+Version: 0.2.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
@@ -21,32 +21,35 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-# Pico-IoC: A Minimalist IoC Container for Python
+# 📦 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.
+**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.
+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
+## ✨ 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.
+* **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
+## 📦 Installation
 ```bash
 pip install pico-ioc
@@ -54,9 +57,7 @@ pip install pico-ioc
 ---
-## Quick Start
-Getting started is simple. Decorate your classes and let Pico-IoC wire them up.
+## 🚀 Quick Start
 ```python
 from pico_ioc import component, init
@@ -83,21 +84,22 @@ print(db.get_data())  # Data from postgresql://user:pass@host/db
 ---
-## More Examples
+## 🧩 Custom Component Keys
-### 🧩 Custom Component Name
+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")
+@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"):  # refer by custom name if you prefer
+    def __init__(self, config: "config"):  # resolve by name
         self._url = config.db_url
 container = init(__name__)
@@ -106,9 +108,12 @@ print(repo._url)           # postgresql://user:pass@localhost/db
 print(container.get("config").db_url)
 ```
-> Pico-IoC prefers **type annotations** to resolve deps; if missing, it falls back to the **parameter name**.
+---
-### 💤 Lazy Factories (only build when used)
+## 🏭 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
@@ -117,7 +122,7 @@ CREATION_COUNTER = {"value": 0}
 @factory_component
 class ServicesFactory:
-    @provides(name="heavy_service")  # returns a LazyProxy by default
+    @provides(key="heavy_service")  # preferred
     def make_heavy(self):
         CREATION_COUNTER["value"] += 1
         return {"payload": "Hello from heavy service"}
@@ -130,7 +135,9 @@ print(svc["payload"])             # triggers creation
 print(CREATION_COUNTER["value"])  # 1
 ```
-### 📦 Project-Style Package Scanning
+---
+## 📦 Project-Style Scanning
 ```
 project_root/
@@ -165,61 +172,62 @@ class ApiClient:
 import pico_ioc
 from myapp.services import ApiClient
-# Scan the whole 'myapp' package
 container = pico_ioc.init("myapp")
 client = container.get(ApiClient)
 print(client.get("status"))  # GET https://api.example.com/status
 ```
 ---
-## API Reference (mini)
+## 🧠 Dependency Resolution Order
-### `init(root_package_or_module) -> PicoContainer`
+When Pico-IoC instantiates a component, it tries to resolve each parameter in this order:
-Initialize the container by scanning a root **package** (str) or **module**. Returns the configured container.
+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
-### `@component(cls=None, *, name: str | None = None)`
+---
-Mark a class as a component. Registered by **class type** by default, or by **name** if provided.
+## 🛠 API Reference
-### `@factory_component`
+### `init(root_package_or_module, *, exclude=None, auto_exclude_caller=True) -> PicoContainer`
-Mark a class as a factory holder. Methods inside can be `@provides(...)`.
+Scan the given root **package** (str) or **module**.
+By default, excludes the calling module.
-### `@provides(name: str, lazy: bool = True)`
+### `@component(cls=None, *, name=None)`
-Declare that a factory method **produces** a component registered under `name`. By default it’s **lazy** (a proxy that creates on first real use).
+Register a class as a component.
+If `name` is given, registers under that string; otherwise under the class type.
----
+### `@factory_component`
-## Testing
+Register a class as a factory of components.
-`pico-ioc` ships with `pytest` tests and a `tox` matrix.
+### `@provides(key=None, *, name=None, lazy=True)`
-```bash
-pip install tox
-tox -e py311           # run on a specific version
-tox                    # run all configured envs
-```
+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.
 ---
-## Contributing
+## 🧪 Testing
-Issues and PRs are welcome. If you spot a bug or have an idea, open an issue!
+```bash
+pip install tox
+tox -e py311
+```
 ---
-## License
+## 📜 License
-MIT — see the [LICENSE](https://opensource.org/licenses/MIT).
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
 ---
-## Authors
+¿Quieres que también te prepare **un ejemplo completo en el README** con `fast_model` y `BaseChatModel` para que quede documentado el nuevo orden de resolución? Así quedaría clarísimo para cualquiera que lo use.
-* **David Perez Cabrera**
-* **Gemini 2.5-Pro**
-* **GPT-5**

pico_ioc-0.2.0/tests/test_pico_ioc.py ADDED Viewed

@@ -0,0 +1,321 @@
+import pytest
+import sys
+import pico_ioc
+# --- Test Environment Setup Fixture ---
+@pytest.fixture
+def test_project(tmp_path):
+    """
+    Creates a fake project in a temporary directory so the pico_ioc scanner
+    can find components/factories via import.
+    """
+    project_root = tmp_path / "test_project"
+    project_root.mkdir()
+    # Make the temp root importable
+    sys.path.insert(0, str(tmp_path))
+    # Turn 'test_project' into a real package
+    (project_root / "__init__.py").touch()
+    # Create the package 'services'
+    package_dir = project_root / "services"
+    package_dir.mkdir()
+    (package_dir / "__init__.py").touch()
+    # Components:
+    # - SimpleService                          (no deps)
+    # - AnotherService                         (depends on SimpleService by type)
+    # - CustomNameService                      (registered by custom name)
+    # - NeedsByName                            (depends by name only)
+    # - NeedsNameVsType                        (name should win over type)
+    # - NeedsTypeFallback                      (fallback to base type via MRO)
+    (package_dir / "components.py").write_text(
+        """
+from pico_ioc import component
+class BaseInterface: ...
+class SubInterface(BaseInterface): ...
+@component
+class SimpleService:
+    def get_id(self):
+        return id(self)
+@component
+class AnotherService:
+    def __init__(self, simple_service: SimpleService):
+        # Will resolve by TYPE because there is no provider bound by the name "simple_service"
+        self.child = simple_service
+@component(name="custom_name_service")
+class CustomNameService:
+    pass
+@component
+class NeedsByName:
+    def __init__(self, fast_model):
+        # Will resolve by NAME, since there will be a provider bound to "fast_model"
+        self.model = fast_model
+@component
+class NeedsNameVsType:
+    def __init__(self, fast_model: BaseInterface):
+        # There will be providers for BOTH the name "fast_model" and the base type.
+        # NAME must win over TYPE.
+        self.model = fast_model
+@component
+class NeedsTypeFallback:
+    def __init__(self, impl: SubInterface):
+        # There will NOT be a provider for the name "impl" nor for SubInterface directly,
+        # but there will be one for BaseInterface → must fallback via MRO.
+        self.impl = impl
+@component
+class MissingDep:
+    def __init__(self, missing):
+        # No provider by name nor type: must raise on resolution.
+        self.missing = missing
+"""
+    )
+    # Factories:
+    # - complex_service (lazy via LazyProxy; counter to assert laziness)
+    # - fast_model      (by NAME)
+    # - base_interface  (by TYPE: BaseInterface)
+    (package_dir / "factories.py").write_text(
+        """
+from pico_ioc import factory_component, provides
+from .components import BaseInterface
+# Used to assert lazy instantiation
+CREATION_COUNTER = {"value": 0}
+FAST_COUNTER = {"value": 0}
+BASE_COUNTER = {"value": 0}
+@factory_component
+class ServiceFactory:
+    @provides(key="complex_service")
+    def create_complex_service(self):
+        # Increment ONLY when the real object is created (not when proxy is returned)
+        CREATION_COUNTER["value"] += 1
+        return "This is a complex service"
+    @provides(key="fast_model")
+    def create_fast_model(self):
+        FAST_COUNTER["value"] += 1
+        return {"who": "fast"}  # any object; dict is convenient for identity checks
+    @provides(key=BaseInterface)
+    def create_base_interface(self):
+        BASE_COUNTER["value"] += 1
+        return {"who": "base"}
+"""
+    )
+    # Optional module that calls init() at import-time:
+    # used to test auto-exclude of the caller (to prevent re-entrancy).
+    (project_root / "entry.py").write_text(
+        """
+import pico_ioc
+import test_project
+# If auto-exclude-caller is on AND _scan_and_configure() honors 'exclude',
+# importing this module during scanning should NOT recurse infinitely.
+ioc = pico_ioc.init(test_project)
+"""
+    )
+    # Yield the root package name used by pico_ioc.init()
+    yield "test_project"
+    # Teardown: remove path, reset container, purge modules from cache
+    sys.path.pop(0)
+    pico_ioc._container = None
+    mods_to_del = [m for m in list(sys.modules.keys()) if m == "test_project" or m.startswith("test_project.")]
+    for m in mods_to_del:
+        sys.modules.pop(m, None)
+# --- Test Suite ---
+def test_simple_component_retrieval(test_project):
+    """A plain component registered by class can be retrieved by its class key."""
+    from test_project.services.components import SimpleService
+    container = pico_ioc.init(test_project)
+    service = container.get(SimpleService)
+    assert service is not None
+    assert isinstance(service, SimpleService)
+def test_dependency_injection_by_type_hint(test_project):
+    """
+    When a constructor parameter has a type hint and no provider is bound by name,
+    the container should resolve it by TYPE.
+    """
+    from test_project.services.components import SimpleService, AnotherService
+    container = pico_ioc.init(test_project)
+    another = container.get(AnotherService)
+    assert another is not None
+    assert isinstance(another.child, SimpleService)
+def test_components_are_singletons_by_default(test_project):
+    """
+    Providers bound by the scanner are singletons: get() returns the same instance.
+    """
+    from test_project.services.components import SimpleService
+    container = pico_ioc.init(test_project)
+    s1 = container.get(SimpleService)
+    s2 = container.get(SimpleService)
+    assert s1 is s2
+    assert s1.get_id() == s2.get_id()
+def test_get_unregistered_component_raises_error(test_project):
+    """
+    Requesting a key with no provider must raise NameError with a helpful message.
+    """
+    container = pico_ioc.init(test_project)
+    class Unregistered: ...
+    with pytest.raises(NameError, match="No provider found for key"):
+        container.get(Unregistered)
+def test_factory_provides_component_by_name(test_project):
+    """
+    A factory method annotated with @provides(key="...") is bound by NAME and is retrievable.
+    """
+    container = pico_ioc.init(test_project)
+    svc = container.get("complex_service")
+    # Proxy must behave like the real string for equality
+    assert svc == "This is a complex service"
+def test_factory_instantiation_is_lazy_and_singleton(test_project):
+    """
+    Factory methods with default lazy=True return a LazyProxy. The real object is created on first use.
+    Also, container should cache the created instance (singleton per key).
+    """
+    from test_project.services.factories import CREATION_COUNTER
+    container = pico_ioc.init(test_project)
+    assert CREATION_COUNTER["value"] == 0
+    proxy = container.get("complex_service")
+    # Accessing attributes/methods of the proxy should trigger creation exactly once
+    assert CREATION_COUNTER["value"] == 0
+    up = proxy.upper()
+    assert up == "THIS IS A COMPLEX SERVICE"
+    assert CREATION_COUNTER["value"] == 1
+    # Re-accessing via the same proxy does not create again
+    _ = proxy.lower()
+    assert CREATION_COUNTER["value"] == 1
+    # Getting the same key again should return the same singleton instance (no extra creations)
+    again = container.get("complex_service")
+    assert again is proxy  # same object returned by container
+    _ = again.strip()
+    assert CREATION_COUNTER["value"] == 1
+def test_component_with_custom_name(test_project):
+    """
+    A component registered by custom name is retrievable by that name,
+    and NOT by its class.
+    """
+    from test_project.services.components import CustomNameService
+    container = pico_ioc.init(test_project)
+    svc = container.get("custom_name_service")
+    assert isinstance(svc, CustomNameService)
+    with pytest.raises(NameError):
+        container.get(CustomNameService)
+def test_resolution_prefers_name_over_type(test_project):
+    """
+    If both a NAME-bound provider and a TYPE-bound provider exist, resolution MUST
+    prefer the NAME (parameter name) over the TYPE hint.
+    """
+    from test_project.services.components import NeedsNameVsType
+    from test_project.services.factories import FAST_COUNTER, BASE_COUNTER
+    container = pico_ioc.init(test_project)
+    comp = container.get(NeedsNameVsType)
+    # "fast_model" name must win → uses the fast provider
+    assert comp.model == {"who": "fast"}
+    assert FAST_COUNTER["value"] == 1
+    # Base provider should NOT be used for this resolution
+    assert BASE_COUNTER["value"] == 0
+def test_resolution_by_name_only(test_project):
+    """
+    When a ctor parameter has NO type hint, the container must resolve strictly by NAME.
+    """
+    from test_project.services.components import NeedsByName
+    from test_project.services.factories import FAST_COUNTER
+    container = pico_ioc.init(test_project)
+    comp = container.get(NeedsByName)
+    assert comp.model == {"who": "fast"}
+    assert FAST_COUNTER["value"] == 1
+def test_resolution_fallback_to_type_mro(test_project):
+    """
+    When there is no provider for the parameter NAME nor the exact TYPE,
+    the container must try TYPE's MRO and use the first available provider.
+    """
+    from test_project.services.components import NeedsTypeFallback
+    from test_project.services.factories import BASE_COUNTER
+    container = pico_ioc.init(test_project)
+    comp = container.get(NeedsTypeFallback)
+    # Resolved via MRO to BaseInterface provider
+    assert comp.impl == {"who": "base"}
+    assert BASE_COUNTER["value"] == 1
+def test_missing_dependency_raises_clear_error(test_project):
+    """
+    If no provider exists for NAME nor TYPE nor MRO, resolution must raise NameError.
+    """
+    from test_project.services.components import MissingDep
+    container = pico_ioc.init(test_project)
+    with pytest.raises(NameError, match="No provider found for key"):
+        container.get(MissingDep)
+@pytest.mark.skipif(
+    not hasattr(pico_ioc, "init"),
+    reason="init not available"
+)
+def test_auto_exclude_caller_prevents_reentrant_scan(test_project):
+    """
+    Smoke test: importing a module that calls pico_ioc.init(root) at import-time
+    should not cause re-entrant scans if init() auto-excludes the caller AND
+    _scan_and_configure honors the 'exclude' predicate.
+    """
+    # If the library correctly auto-excludes the caller and passes 'exclude'
+    # into the scanner (which must skip excluded modules), this import should be safe.
+    __import__("test_project.entry")

pico_ioc-0.1.1/src/pico_ioc/_version.py DELETED Viewed

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

pico_ioc-0.1.1/tests/test_pico_ioc.py DELETED Viewed

@@ -1,178 +0,0 @@
-# tests/test_pico_ioc.py
-import pytest
-import sys
-import pico_ioc
-# --- Test Environment Setup Fixture ---
-@pytest.fixture
-def test_project(tmp_path):
-    """
-    Creates a fake project structure in a temporary directory
-    so that the pico_ioc scanner can find the components.
-    """
-    project_root = tmp_path / "test_project"
-    project_root.mkdir()
-    # Add the root directory to the Python path so modules can be imported
-    sys.path.insert(0, str(tmp_path))
-    # >>> THE LINE THAT FIXES THE PROBLEM <<<
-    # Turn 'test_project' into a regular package.
-    (project_root / "__init__.py").touch()
-    # Create the package and modules with test components
-    package_dir = project_root / "services"
-    package_dir.mkdir()
-    # __init__.py file to turn 'services' into a sub-package
-    (package_dir / "__init__.py").touch()
-    # Module with simple components and components with dependencies
-    (package_dir / "components.py").write_text("""
-from pico_ioc import component
-@component
-class SimpleService:
-    def get_id(self):
-        return id(self)
-@component
-class AnotherService:
-    def __init__(self, simple_service: SimpleService):
-        self.child = simple_service
-@component(name="custom_name_service")
-class CustomNameService:
-    pass
-""")
-    # Module with a component factory
-    (package_dir / "factories.py").write_text("""
-from pico_ioc import factory_component, provides
-# To test that instantiation is lazy
-CREATION_COUNTER = {"value": 0}
-@factory_component
-class ServiceFactory:
-    @provides(name="complex_service")
-    def create_complex_service(self):
-        CREATION_COUNTER["value"] += 1
-        return "This is a complex service"
-""")
-    # Return the root package name for init() to use
-    yield "test_project"
-    sys.path.pop(0)
-    # Reset the global pico_ioc container to isolate tests.
-    pico_ioc._container = None
-    # Purge the temporary package from the module cache so each test starts
-    # with a fresh module state (e.g., CREATION_COUNTER resets to 0).
-    mods_to_del = [
-        m for m in list(sys.modules.keys())
-        if m == "test_project" or m.startswith("test_project.")
-    ]
-    for m in mods_to_del:
-        sys.modules.pop(m, None)
-# --- Test Suite ---
-def test_simple_component_retrieval(test_project):
-    """Verifies that a simple component can be registered and retrieved."""
-    # Import the TEST classes after the fixture has created them
-    from test_project.services.components import SimpleService
-    container = pico_ioc.init(test_project)
-    service = container.get(SimpleService)
-    assert service is not None
-    assert isinstance(service, SimpleService)
-def test_dependency_injection(test_project):
-    """Verifies that a dependency is correctly injected into another component."""
-    from test_project.services.components import SimpleService, AnotherService
-    container = pico_ioc.init(test_project)
-    another_service = container.get(AnotherService)
-    assert another_service is not None
-    assert hasattr(another_service, "child")
-    assert isinstance(another_service.child, SimpleService)
-def test_components_are_singletons_by_default(test_project):
-    """Verifies that get() always returns the same instance for a component."""
-    from test_project.services.components import SimpleService
-    container = pico_ioc.init(test_project)
-    service1 = container.get(SimpleService)
-    service2 = container.get(SimpleService)
-    assert service1 is service2
-    assert service1.get_id() == service2.get_id()
-def test_get_unregistered_component_raises_error(test_project):
-    """Verifies that requesting an unregistered component raises a NameError."""
-    container = pico_ioc.init(test_project)
-    class UnregisteredClass:
-        pass
-    with pytest.raises(NameError, match="No provider found for key"):
-        container.get(UnregisteredClass)
-def test_factory_provides_component(test_project):
-    """Verifies that a component created by a factory can be retrieved."""
-    container = pico_ioc.init(test_project)
-    service = container.get("complex_service")
-    # The object is a proxy, but it should delegate the comparison
-    assert service == "This is a complex service"
-def test_factory_instantiation_is_lazy(test_project):
-    """
-    Verifies that a factory's @provides method is only executed
-    when the object is first accessed.
-    """
-    # Import the counter from the test factory
-    from test_project.services.factories import CREATION_COUNTER
-    container = pico_ioc.init(test_project)
-    # Initially, the counter must be 0 because nothing has been created yet
-    assert CREATION_COUNTER["value"] == 0
-    # We get the proxy, but this should NOT trigger the creation
-    service_proxy = container.get("complex_service")
-    assert CREATION_COUNTER["value"] == 0
-    # Now we access an attribute of the real object (through the proxy)
-    # This SHOULD trigger the creation
-    result = service_proxy.upper() # .upper() is called on the real string
-    assert CREATION_COUNTER["value"] == 1
-    assert result == "THIS IS A COMPLEX SERVICE"
-    # If we access it again, the counter should not increment
-    _ = service_proxy.lower()
-    assert CREATION_COUNTER["value"] == 1
-def test_component_with_custom_name(test_project):
-    """Verifies that a component with a custom name can be registered and retrieved."""
-    from test_project.services.components import CustomNameService
-    container = pico_ioc.init(test_project)
-    # We get the service using its custom name
-    service = container.get("custom_name_service")
-    assert isinstance(service, CustomNameService)
-    # Verify that requesting it by its class fails, as it was registered by name
-    with pytest.raises(NameError):
-        container.get(CustomNameService)