pico-ioc 0.1.1__tar.gz → 0.2.1__tar.gz

{pico_ioc-0.1.1 → pico_ioc-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 0.1.1
+Version: 0.2.1
 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.1}/README.md

@@ -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.1}/src/pico_ioc/__init__.py

@@ -1,7 +1,6 @@
-# src/pico_ioc/__init__.py
-
-import functools, inspect, pkgutil, importlib, logging, sys
-from typing import Callable, Any, Iterator, AsyncIterator
+import functools, inspect, pkgutil, importlib, logging
+from typing import Callable, Any, Optional
+from contextvars import ContextVar
 
 try:
     # written at build time by setuptools-scm
@@ -11,18 +10,40 @@ except Exception:  # pragma: no cover
 
 __all__ = ["__version__"]
 
+# ------------------------------------------------------------------------------
+# 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 = {}
-        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:
+        # 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."
+            )
+
         if key in self._singletons:
             return self._singletons[key]
         if key in self._providers:
@@ -136,21 +157,63 @@ 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")
+
+    # 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:]:
+                if base is object:
+                    break
+                if container.has(base):
+                    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 _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__ + '.'):
+        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):
-                if hasattr(obj, '_is_component'):
+                if getattr(obj, '_is_component', False):
                     component_classes.append(obj)
-                elif hasattr(obj, '_is_factory_component'):
+                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
     for factory_cls in factory_classes:
         try:
             sig = inspect.signature(factory_cls.__init__)
@@ -161,30 +224,64 @@ def _scan_and_configure(package_or_name, container: PicoContainer):
         except Exception as e:
             logging.error(f"  ❌ Error in factory {factory_cls.__name__}: {e}", exc_info=True)
 
+    # Register components
     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 = {}
-            for p in sig.parameters.values():
-                if p.name == 'self' or p.kind in (
-                    inspect.Parameter.VAR_POSITIONAL,  # *args
-                    inspect.Parameter.VAR_KEYWORD,     # **kwargs
-                ):
-                    continue
-                dep_key = p.annotation if p.annotation is not inspect._empty else p.name
-                deps[p.name] = container.get(dep_key)
+            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):
+
+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.
+    """
     global _container
     if _container:
         return _container
+
+    combined_exclude = exclude
+    if auto_exclude_caller:
+        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)
+
+    tok = _scanning.set(True)
+    try:
+        _scan_and_configure(root_package, _container, exclude=combined_exclude)
+    finally:
+        _scanning.reset(tok)
+
     logging.info("✅ Container configured and ready.")
     return _container
 
@@ -195,19 +292,27 @@ 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):
+    """
+    Declare that a factory method provides a component under 'key'.
+    By default, returns a LazyProxy that instantiates upon first real use.
+    """
     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)
+        setattr(wrapper, '_provides_name', key)  # legacy-compatible storage
         return wrapper
     return decorator
 
 def component(cls=None, *, name: str = None):
-    def decorator(cls):
-        setattr(cls, '_is_component', True)
-        setattr(cls, '_component_key', name if name is not None else cls)
-        return cls
+    """
+    Mark a class as a component. Registered by class type by default,
+    or by 'name' if provided.
+    """
+    def decorator(c):
+        setattr(c, '_is_component', True)
+        setattr(c, '_component_key', name if name is not None else c)
+        return c
     return decorator(cls) if cls else decorator
 

pico_ioc-0.2.1/src/pico_ioc/_version.py

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