pico-ioc 2.0.1__tar.gz → 2.0.3__tar.gz

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/CHANGELOG.md

@@ -5,6 +5,91 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.html).
 
+---
+
+## [2.0.3] - 2025-10-26
+
+### Fixed
+
+- Injection now falls back from an annotated key to the parameter name when the annotated key is unbound, enabling resolution against string-key providers registered via `@provides("name")`.
+- `ProviderNotFoundError` includes the requesting origin (component or key) to aid debugging and test assertions.
+- Unified sync/async resolution path in `PicoContainer`:
+  - `get()` raises `AsyncResolutionError` if a provider returns an awaitable, guiding users to `aget()`.
+  - `aget()` awaits awaitables and applies aspects and caching consistently.
+  - Observers receive accurate resolve timings in both paths.
+
+### Added
+
+- `AsyncResolutionError` to signal misuse of `get()` when a provider is async.
+- More informative tracer notes for parameter binding.
+
+### Internal
+
+- `ComponentFactory.get()` now accepts an `origin` to enrich `ProviderNotFoundError` messages.
+- Lazy proxy creation calls `factory.get(key, origin="lazy")` to attribute provenance.
+- Public API exports updated to include `AsyncResolutionError`.
+
+### Compatibility
+
+- No public API breaking changes. Internal factory signature changed but remains encapsulated within the container/registrar.
+
+---
+
+## [2.0.2] - 2025-10-26
+
+### Fixed 🧩
+
+* **`@provides` Decorator Execution**
+  Corrected an issue where the `@provides` decorator executed its wrapped function prematurely during module import, leading to runtime errors like `TypeError: Service() takes no arguments`.
+  The decorator now properly registers provider metadata without invoking the function until dependency resolution time.
+
+### Added ✨
+
+* **`FlatDictSource` Configuration Provider**
+  Introduced a lightweight configuration source for flat in-memory dictionaries.
+  Supports optional key prefixing and case sensitivity control for simple, programmatic configuration injection.
+
+### Internal 🔧
+
+* Updated type imports and registration logic in `api.py` to support `Mapping` for the new configuration source.
+* Added `FlatDictSource` to the public API (`__all__` and import namespace).
+
+### Notes 📝
+
+* Fully backward compatible.
+* This patch release focuses on decorator correctness and configuration flexibility improvements.
+
+---
+
+## [2.0.1] - 2025-10-25
+
+### Added ✨
+
+- **ADR-0009: Flexible `@provides` Support**  
+  Implemented support for using `@provides` in additional contexts:
+  - `@staticmethod` methods within `@factory` classes  
+  - `@classmethod` methods within `@factory` classes  
+  - Module-level functions  
+  These new provider types are discovered automatically during module scanning and participate fully in dependency resolution, validation, and graph generation.
+
+- **Dependency Graph and Validation Enhancements**  
+  - `_build_resolution_graph` now includes edges for all `@provides` functions, regardless of where they are defined.  
+  - Fail-fast validation checks now cover static/class/module-level providers, reporting missing bindings consistently.  
+  - Scope inference and promotion logic apply equally to these new provider types.
+
+### Documentation 📚
+
+- Expanded `docs/overview.md` to document the new flexible provider options (`@staticmethod`, `@classmethod`, module-level functions).  
+- Updated `docs/guide.md` with practical examples showing when to use each style of provider.  
+- Linked ADR-0009 for design rationale and migration guidance.
+
+### Notes 📝
+
+- This is a **minor feature release** introducing a major ergonomics improvement (ADR-0009).  
+- Fully backward compatible with existing factories, components, and configuration mechanisms.  
+- Encourages a lighter, more Pythonic style for simple provider declarations.
+
+
 ---
 
 ## [2.0.0] - 2025-10-23
@@ -58,37 +143,6 @@ This version marks a significant redesign and the first major public release, es
 * Added comprehensive test suite covering core features, async behavior, AOP, configuration, scopes, and error handling.
 * Introduced patterns for testing with overrides and profiles.
 
----
-
-## [2.0.1] - 2025-10-25
-
-### Added ✨
-
-- **ADR-0009: Flexible `@provides` Support**  
-  Implemented support for using `@provides` in additional contexts:
-  - `@staticmethod` methods within `@factory` classes  
-  - `@classmethod` methods within `@factory` classes  
-  - Module-level functions  
-  These new provider types are discovered automatically during module scanning and participate fully in dependency resolution, validation, and graph generation.
-
-- **Dependency Graph and Validation Enhancements**  
-  - `_build_resolution_graph` now includes edges for all `@provides` functions, regardless of where they are defined.  
-  - Fail-fast validation checks now cover static/class/module-level providers, reporting missing bindings consistently.  
-  - Scope inference and promotion logic apply equally to these new provider types.
-
-### Documentation 📚
-
-- Expanded `docs/overview.md` to document the new flexible provider options (`@staticmethod`, `@classmethod`, module-level functions).  
-- Updated `docs/guide.md` with practical examples showing when to use each style of provider.  
-- Linked ADR-0009 for design rationale and migration guidance.
-
-### Notes 📝
-
-- This is a **minor feature release** introducing a major ergonomics improvement (ADR-0009).  
-- Fully backward compatible with existing factories, components, and configuration mechanisms.  
-- Encourages a lighter, more Pythonic style for simple provider declarations.
-
-
 ---
 
 ## [<2.0.0]

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.0.1
+Version: 2.0.3
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/src/pico_ioc/__init__.py

@@ -11,6 +11,7 @@ from .exceptions import (
     ValidationError,
     InvalidBindingError,
     EventBusClosedError,
+    AsyncResolutionError,
 )
 from .api import (
     component,
@@ -23,6 +24,7 @@ from .api import (
     ConfigSource,
     EnvSource,
     FileSource,
+    FlatDictSource,
     init,
     configured,
 )
@@ -50,6 +52,7 @@ __all__ = [
     "SerializationError",
     "ValidationError",
     "InvalidBindingError",
+    "AsyncResolutionError",
     "EventBusClosedError",
     "component",
     "factory",
@@ -76,6 +79,7 @@ __all__ = [
     "EnvSource",
     "FileSource",
     "ConfigSource",
+    "FlatDictSource",
     "init",
     "configured",
     "EventBus",

pico_ioc-2.0.3/src/pico_ioc/_version.py

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

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/src/pico_ioc/api.py

@@ -6,10 +6,9 @@ import importlib
 import pkgutil
 import logging
 from dataclasses import is_dataclass, fields, dataclass, MISSING
-from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Tuple, Union, get_args, get_origin, Annotated, Protocol
+from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Tuple, Union, get_args, get_origin, Annotated, Protocol, Mapping
 from .constants import LOGGER, PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
 from .exceptions import (
-    ProviderNotFoundError,
     CircularDependencyError,
     ScopeError,
     ConfigurationError,
@@ -54,6 +53,31 @@ class FileSource:
             return str(v)
         return None
 
+class FlatDictSource(ConfigSource):
+    def __init__(self, data: Mapping[str, Any], prefix: str = "", case_sensitive: bool = True):
+        base = dict(data)
+        if case_sensitive:
+            self._data = {str(k): v for k, v in base.items()}
+            self._prefix = prefix
+        else:
+            self._data = {str(k).upper(): v for k, v in base.items()}
+            self._prefix = prefix.upper()
+        self._case_sensitive = case_sensitive
+
+    def get(self, key: str) -> Optional[str]:
+        if not key:
+            return None
+        k = f"{self._prefix}{key}" if self._prefix else key
+        if not self._case_sensitive:
+            k = k.upper()
+        v = self._data.get(k)
+        if v is None:
+            return None
+        if isinstance(v, (str, int, float, bool)):
+            return str(v)
+        return None
+
+
 def _meta_get(obj: Any) -> Dict[str, Any]:
     m = getattr(obj, PICO_META, None)
     if m is None:
@@ -132,29 +156,21 @@ def factory(
         return c
     return dec(cls) if cls else dec
 
-def provides(
-    key: Any,
-    *,
-    name: Any = None,
-    qualifiers: Iterable[str] = (),
-    scope: str = "singleton",
-    primary: bool = False,
-    lazy: bool = False,
-    conditional_profiles: Iterable[str] = (),
-    conditional_require_env: Iterable[str] = (),
-    conditional_predicate: Optional[Callable[[], bool]] = None,
-    on_missing_selector: Optional[object] = None,
-    on_missing_priority: int = 0,
-):
-    def dec(fn):
+def provides(*dargs, **dkwargs):
+    def _apply(fn, key_hint, *, name=None, qualifiers=(), scope="singleton", primary=False, lazy=False, conditional_profiles=(), conditional_require_env=(), conditional_predicate=None, on_missing_selector=None, on_missing_priority=0):
         target = fn.__func__ if isinstance(fn, (staticmethod, classmethod)) else fn
-        @functools.wraps(target)
-        def w(*a, **k):
-            return target(*a, **k)
-        setattr(w, PICO_INFRA, "provides")
-        setattr(w, PICO_NAME, name if name is not None else key)
-        setattr(w, PICO_KEY, key)
-        m = _meta_get(w)
+        inferred_key = key_hint
+        if inferred_key is MISSING:
+            rt = _get_return_type(target)
+            if isinstance(rt, type):
+                inferred_key = rt
+            else:
+                inferred_key = getattr(target, "__name__", str(target))
+        setattr(target, PICO_INFRA, "provides")
+        pico_name = name if name is not None else (inferred_key if isinstance(inferred_key, str) else getattr(target, "__name__", str(target)))
+        setattr(target, PICO_NAME, pico_name)
+        setattr(target, PICO_KEY, inferred_key)
+        m = _meta_get(target)
         m["qualifier"] = tuple(str(q) for q in qualifiers or ())
         m["scope"] = scope
         if primary:
@@ -169,8 +185,16 @@ def provides(
             }
         if on_missing_selector is not None:
             m["on_missing"] = {"selector": on_missing_selector, "priority": int(on_missing_priority)}
-        return w
-    return dec
+        return fn
+
+    if dargs and len(dargs) == 1 and inspect.isfunction(dargs[0]) and not dkwargs:
+        fn = dargs[0]
+        return _apply(fn, MISSING)
+    else:
+        key = dargs[0] if dargs else MISSING
+        def _decorator(fn):
+            return _apply(fn, key, **dkwargs)
+        return _decorator
 
 class Qualifier(str):
     __slots__ = ()
@@ -384,8 +408,18 @@ def _resolve_args(callable_obj: Callable[..., Any], pico: "PicoContainer") -> Di
     try:
         for kind, name, data in plan:
             if kind == "key":
-                tracer.note_param(data if isinstance(data, (str, type)) else name, name)
-                kwargs[name] = pico.get(data)
+                primary_key = data
+                tracer.note_param(primary_key, name)
+                try:
+                    kwargs[name] = pico.get(primary_key)
+                except ProviderNotFoundError as first_error:
+                    if primary_key != name:
+                        try:
+                            kwargs[name] = pico.get(name)
+                        except ProviderNotFoundError:
+                            raise first_error from None
+                    else:
+                        raise first_error from None
             else:
                 vals = [pico.get(k) for k in data]
                 kwargs[name] = vals
@@ -549,7 +583,7 @@ class Registrar:
             deferred.attach(pico, locator)
         for key, md in list(self._metadata.items()):
             if md.lazy:
-                original = self._factory.get(key)
+                original = self._factory.get(key, origin='lazy')
                 def lazy_proxy_provider(_orig=original, _p=pico):
                     return UnifiedComponentProxy(container=_p, object_creator=_orig)
                 self._factory.bind(key, lazy_proxy_provider)

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/src/pico_ioc/container.py

@@ -4,7 +4,7 @@ import contextvars
 from typing import Any, Dict, List, Optional, Tuple, overload, Union
 from contextlib import contextmanager
 from .constants import LOGGER, PICO_META
-from .exceptions import CircularDependencyError, ComponentCreationError, ProviderNotFoundError
+from .exceptions import CircularDependencyError, ComponentCreationError, ProviderNotFoundError, AsyncResolutionError
 from .factory import ComponentFactory
 from .locator import ComponentLocator
 from .scope import ScopedCaches, ScopeManager
@@ -173,85 +173,88 @@ class PicoContainer:
                     return k
         return key
 
-    @overload
-    def get(self, key: type) -> Any: ...
-    @overload
-    def get(self, key: str) -> Any: ...
-    def get(self, key: KeyT) -> Any:
+    def _resolve_or_create_internal(self, key: KeyT) -> Tuple[Any, float, bool]:
         key = self._canonical_key(key)
         cache = self._cache_for(key)
         cached = cache.get(key)
         if cached is not None:
             self.context.cache_hit_count += 1
             for o in self._observers: o.on_cache_hit(key)
-            return cached
+            return cached, 0.0, True
+
         import time as _tm
         t0 = _tm.perf_counter()
         chain = list(_resolve_chain.get())
-        for k in chain:
-            if k == key:
+
+        for k_in_chain in chain:
+            if k_in_chain == key:
                 details = self._tracer.describe_cycle(tuple(chain), key, self._locator)
                 raise ComponentCreationError(key, CircularDependencyError(chain, key, details=details))
+
         token_chain = _resolve_chain.set(tuple(chain + [key]))
         token_container = self.activate()
         token_tracer = self._tracer.enter(key, via="provider")
+
+        requester = chain[-1] if chain else None
+        instance_or_awaitable = None
+
         try:
-            provider = self._factory.get(key)
+            provider = self._factory.get(key, origin=requester)
             try:
-                instance = provider()
+                instance_or_awaitable = provider()
             except ProviderNotFoundError as e:
                 raise
-            except Exception as e:
-                raise ComponentCreationError(key, e) from e
-            instance = self._maybe_wrap_with_aspects(key, instance)
-            cache.put(key, instance)
-            self.context.resolve_count += 1
+            except Exception as creation_error:
+                raise ComponentCreationError(key, creation_error) from creation_error
+
             took_ms = (_tm.perf_counter() - t0) * 1000
-            for o in self._observers: o.on_resolve(key, took_ms)
-            return instance
+            return instance_or_awaitable, took_ms, False
+
         finally:
             self._tracer.leave(token_tracer)
             _resolve_chain.reset(token_chain)
             self.deactivate(token_container)
+            
+    @overload
+    def get(self, key: type) -> Any: ...
+    @overload
+    def get(self, key: str) -> Any: ...
+    def get(self, key: KeyT) -> Any:
+        instance_or_awaitable, took_ms, was_cached = self._resolve_or_create_internal(key)
+
+        if was_cached:
+            return instance_or_awaitable
+
+        instance = instance_or_awaitable
+        if inspect.isawaitable(instance):
+            key_name = getattr(key, '__name__', str(key))
+            raise AsyncResolutionError(key)
+
+        final_instance = self._maybe_wrap_with_aspects(key, instance)
+        cache = self._cache_for(key)
+        cache.put(key, final_instance)
+        self.context.resolve_count += 1
+        for o in self._observers: o.on_resolve(key, took_ms)
+
+        return final_instance
 
     async def aget(self, key: KeyT) -> Any:
-        key = self._canonical_key(key)
+        instance_or_awaitable, took_ms, was_cached = self._resolve_or_create_internal(key)
+
+        if was_cached:
+            return instance_or_awaitable
+
+        instance = instance_or_awaitable
+        if inspect.isawaitable(instance_or_awaitable):
+            instance = await instance_or_awaitable
+
+        final_instance = self._maybe_wrap_with_aspects(key, instance)
         cache = self._cache_for(key)
-        cached = cache.get(key)
-        if cached is not None:
-            self.context.cache_hit_count += 1
-            for o in self._observers: o.on_cache_hit(key)
-            return cached
-        import time as _tm
-        t0 = _tm.perf_counter()
-        chain = list(_resolve_chain.get())
-        for k in chain:
-            if k == key:
-                details = self._tracer.describe_cycle(tuple(chain), key, self._locator)
-                raise ComponentCreationError(key, CircularDependencyError(chain, key, details=details))
-        token_chain = _resolve_chain.set(tuple(chain + [key]))
-        token_container = self.activate()
-        token_tracer = self._tracer.enter(key, via="provider")
-        try:
-            provider = self._factory.get(key)
-            try:
-                instance = provider()
-                if inspect.isawaitable(instance):
-                    instance = await instance
-            except ProviderNotFoundError as e:
-                raise
-            except Exception as e:
-                raise ComponentCreationError(key, e) from e
-            instance = self._maybe_wrap_with_aspects(key, instance)
-            cache.put(key, instance)
-            self.context.resolve_count += 1
-            took_ms = (_tm.perf_counter() - t0) * 1000
-            for o in self._observers: o.on_resolve(key, took_ms)
-            return instance
-        finally:
-            self._tracer.leave(token_tracer)
-            _resolve_chain.reset(token_chain)
-            self.deactivate(token_container)
+        cache.put(key, final_instance)
+        self.context.resolve_count += 1
+        for o in self._observers: o.on_resolve(key, took_ms)
+
+        return final_instance
 
     def _resolve_type_key(self, key: type):
         if not self._locator:

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/src/pico_ioc/exceptions.py

@@ -4,9 +4,15 @@ class PicoError(Exception):
     pass
 
 class ProviderNotFoundError(PicoError):
-    def __init__(self, key: Any):
-        super().__init__(f"Provider not found for key: {getattr(key, '__name__', key)}")
+    def __init__(self, key: Any, origin: Any | None = None):
+        key_name = getattr(key, '__name__', str(key))
+        origin_name = getattr(origin, '__name__', str(origin)) if origin else "init"
+        super().__init__(
+            f"Provider for key '{key_name}' not found "
+            f"(required by: '{origin_name}')"
+        )
         self.key = key
+        self.origin = origin
 
 class CircularDependencyError(PicoError):
     def __init__(self, chain: Iterable[Any], current: Any, details: str | None = None, hint: str | None = None):
@@ -51,6 +57,15 @@ class InvalidBindingError(ValidationError):
         super().__init__("Invalid bindings:\n" + "\n".join(f"- {e}" for e in errors))
         self.errors = errors
 
+class AsyncResolutionError(PicoError):
+    def __init__(self, key: Any):
+        key_name = getattr(key, '__name__', str(key))
+        super().__init__(
+            f"Synchronous get() received an awaitable for key '{key_name}'. "
+            "Use aget() instead."
+        )
+        self.key = key
+        
 class EventBusError(PicoError):
     def __init__(self, msg: str):
         super().__init__(msg)

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/src/pico_ioc/factory.py

@@ -28,9 +28,9 @@ class ComponentFactory:
         self._providers[key] = provider
     def has(self, key: KeyT) -> bool:
         return key in self._providers
-    def get(self, key: KeyT) -> Provider:
+    def get(self, key: KeyT, origin: KeyT) -> Provider:
         if key not in self._providers:
-            raise ProviderNotFoundError(key)
+            raise ProviderNotFoundError(key, origin)
         return self._providers[key]
 
 class DeferredProvider:

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/src/pico_ioc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.0.1
+Version: 2.0.3
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/tests/test_pico_extends.py

@@ -188,12 +188,12 @@ def test_provider_not_found_error():
     container = init(types.ModuleType("empty_mod"))
     with pytest.raises(ProviderNotFoundError) as e_str:
         container.get("non_existent_key")
-    assert "Provider not found for key: non_existent_key" in str(e_str.value)
+    assert "Provider for key 'non_existent_key' not found" in str(e_str.value)
     class NonExistentClass:
         pass
     with pytest.raises(ProviderNotFoundError) as e_type:
         container.get(NonExistentClass)
-    assert "Provider not found for key: NonExistentClass" in str(e_type.value)
+    assert "Provider for key 'NonExistentClass' not found" in str(e_type.value)
 
 def test_configuration_error_missing_value():
     config_module = types.ModuleType("config_test_mod")

{pico_ioc-2.0.1 → pico_ioc-2.0.3}/tests/test_pico_integration.py

@@ -1,7 +1,9 @@
+# tests/test_pico_integration.py
 import pytest
 import os
 import json
 import contextvars
+import types
 from dataclasses import dataclass
 from typing import List, Optional, Annotated, Callable, Any, Protocol
 import logging
@@ -193,6 +195,35 @@ for item in definitions:
 
 test_scopes = {"request": request_scope}
 
+class BaseNamedService:
+    def get_name(self) -> str:
+        return "Base"
+
+class ConcreteNamedService(BaseNamedService):
+    def get_name(self) -> str:
+        return "ConcreteViaStringKey"
+
+@component
+class NeedsNamedServiceByTypeWithFallback:
+    def __init__(self, named_service: BaseNamedService):
+        self.injected_service = named_service
+
+def build_fallback_test_module():
+    m = types.ModuleType("fallback_test_module")
+    @provides("named_service")
+    def build_concrete() -> ConcreteNamedService:
+        return ConcreteNamedService()
+    setattr(m, "NeedsNamedServiceByTypeWithFallback", NeedsNamedServiceByTypeWithFallback)
+    setattr(m, "build_concrete", build_concrete)
+    return m
+
+def test_resolve_fallback_to_parameter_name():
+    test_mod = build_fallback_test_module()
+    container = init(modules=[test_mod])
+    instance = container.get(NeedsNamedServiceByTypeWithFallback)
+    assert isinstance(instance.injected_service, ConcreteNamedService)
+    assert instance.injected_service.get_name() == "ConcreteViaStringKey"
+
 def test_basic_di():
     container = init(test_module)
     instance_b = container.get(ServiceBImpl)
@@ -314,4 +345,3 @@ def test_cleanup_called():
     container.cleanup_all()
     assert holder.closed
     assert "ResourceHolder closed" in log_capture
-

pico_ioc-2.0.1/src/pico_ioc/_version.py

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