pico-ioc 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

pico_ioc/__init__.py

@@ -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/_version.py

@@ -1 +1 @@
-__version__ = '0.1.0'
+__version__ = '0.2.0'

pico_ioc-0.2.0.dist-info/METADATA

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

pico_ioc-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+pico_ioc/__init__.py,sha256=JkCWRwZb_Mv86Q6gI7wJnsFuKWh0A0B7u-uuAfyeF6Y,11781
+pico_ioc/_version.py,sha256=FVHPBGkfhbQDi_z3v0PiKJrXXqXOx0vGW_1VaqNJi7U,22
+pico_ioc-0.2.0.dist-info/METADATA,sha256=CgJTdTIs1-MeabncD7fl9sez6t5a41jdYVea8qUDKOY,6599
+pico_ioc-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-0.2.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-0.2.0.dist-info/RECORD,,

pico_ioc-0.1.0.dist-info/METADATA

@@ -1,22 +0,0 @@
-Metadata-Version: 2.4
-Name: pico-ioc
-Version: 0.1.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-0.1.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-pico_ioc/__init__.py,sha256=SI-ee8rpiNU0f3uTndpTmBmZJ5RZG8MUSGOJXroJfKk,9710
-pico_ioc/_version.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
-pico_ioc-0.1.0.dist-info/METADATA,sha256=VZHRU852qmS5KyavUYx2DJFjVRurY96bJy_I4qKNOsI,1090
-pico_ioc-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-0.1.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-0.1.0.dist-info/RECORD,,