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

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

@@ -7,56 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.h
 
 ---
 
-## [2.0.0] - 2025-10-23
+## [2.0.3] - 2025-10-26
 
-This version marks a significant redesign and the first major public release, establishing the core architecture and feature set based on the principles outlined in the Architecture Decision Records (ADRs).
+### Fixed
 
-### 🚀 Highlights
+- 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.
 
-* **Async-Native Core:** Introduced first-class `async`/`await` support across component resolution (`container.aget`), initialization (`__ainit__`), lifecycle hooks (`@configure`, `@cleanup`), AOP interceptors, and the event bus (ADR-001).
-* **Tree-Based Configuration:** Added `@configured` decorator and `TreeSource` protocol for binding complex, nested configuration (YAML/JSON) to dataclass graphs, including interpolation and type coercion (ADR-002).
-* **Context-Aware Scopes:** Implemented `contextvars`-based scopes (e.g., `"request"`, `"session"`) for managing component lifecycles tied to specific contexts (ADR-003).
-* **Observability Features:** Integrated container context (`container_id`, `as_current`), basic stats (`container.stats()`), observer protocol (`ContainerObserver`), and dependency graph export (`container.export_graph()`) (ADR-004).
-* **Aspect-Oriented Programming (AOP):** Implemented method interception via `MethodInterceptor` protocol and `@intercepted_by` decorator, using a dynamic proxy (`UnifiedComponentProxy`) (ADR-005).
-* **Eager Startup Validation:** Added fail-fast validation during `init()` to detect missing dependencies and configuration errors before runtime (ADR-006).
-* **Built-in Event Bus:** Included an asynchronous, in-process event bus (`EventBus`, `@subscribe`, `AutoSubscriberMixin`) for decoupled communication (ADR-007).
-* **Explicit Circular Dependency Handling:** Implemented detection and fail-fast for circular dependencies, requiring explicit resolution patterns (ADR-008).
-* **Unified Decorator API:** Consolidated component metadata into parameterized decorators (`@component`, `@factory`, `@provides`), removing older stacked decorators (ADR-009).
+### Added
 
-### ✨ Added
+- `AsyncResolutionError` to signal misuse of `get()` when a provider is async.
+- More informative tracer notes for parameter binding.
 
-* Core registration decorators: `@component`, `@factory`, `@provides`.
-* Configuration decorators: `@configuration` (flat key-value) and `@configured` (tree-based).
-* Lifecycle decorators: `@configure`, `@cleanup`.
-* AOP decorator: `@intercepted_by`.
-* Event bus decorator: `@subscribe`.
-* Health check decorator: `@health`.
-* Async resolution: `container.aget()` and `__ainit__` convention.
-* Async cleanup: `container.cleanup_all_async()`.
-* Qualifier support (`Qualifier` class) for list injection (`Annotated[List[Type], Qualifier(...)]`).
-* Support for `lazy=True` parameter for deferred component instantiation.
-* Conditional binding parameters (`conditional_profiles`, `conditional_require_env`, `conditional_predicate`).
-* Fallback binding parameters (`on_missing_selector`, `on_missing_priority`).
-* Primary selection parameter (`primary=True`).
-* Testing support via `init(overrides={...})` and `init(profiles=(...))`.
-* Container context management (`as_current`, `get_current`, `shutdown`, `all_containers`).
-* Scope management API (`activate_scope`, `deactivate_scope`, `scope` context manager).
-* Configuration sources: `EnvSource`, `FileSource` (flat); `JsonTreeSource`, `YamlTreeSource`, `DictSource` (tree).
-* Protocols for extension: `MethodInterceptor`, `ContainerObserver`, `ScopeProtocol`, `ConfigSource`, `TreeSource`.
+### Internal
 
-### ⚠️ Breaking Changes
+- `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`.
 
-* Complete redesign compared to any prior internal/unreleased versions. APIs are not backward compatible.
-* Requires Python 3.10+.
+### Compatibility
 
-### 📚 Docs
+- No public API breaking changes. Internal factory signature changed but remains encapsulated within the container/registrar.
 
-* Established new documentation structure including ADRs, Architecture, User Guide, Advanced Features, Cookbook, Integrations, and API Reference.
+---
 
-### 🧪 Testing
+## [2.0.2] - 2025-10-26
 
-* Added comprehensive test suite covering core features, async behavior, AOP, configuration, scopes, and error handling.
-* Introduced patterns for testing with overrides and profiles.
+### 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.
 
 ---
 
@@ -91,29 +92,56 @@ This version marks a significant redesign and the first major public release, es
 
 ---
 
-## [2.0.2] - 2025-10-26
+## [2.0.0] - 2025-10-23
 
-### Fixed 🧩
+This version marks a significant redesign and the first major public release, establishing the core architecture and feature set based on the principles outlined in the Architecture Decision Records (ADRs).
 
-* **`@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.
+### 🚀 Highlights
 
-### Added ✨
+* **Async-Native Core:** Introduced first-class `async`/`await` support across component resolution (`container.aget`), initialization (`__ainit__`), lifecycle hooks (`@configure`, `@cleanup`), AOP interceptors, and the event bus (ADR-001).
+* **Tree-Based Configuration:** Added `@configured` decorator and `TreeSource` protocol for binding complex, nested configuration (YAML/JSON) to dataclass graphs, including interpolation and type coercion (ADR-002).
+* **Context-Aware Scopes:** Implemented `contextvars`-based scopes (e.g., `"request"`, `"session"`) for managing component lifecycles tied to specific contexts (ADR-003).
+* **Observability Features:** Integrated container context (`container_id`, `as_current`), basic stats (`container.stats()`), observer protocol (`ContainerObserver`), and dependency graph export (`container.export_graph()`) (ADR-004).
+* **Aspect-Oriented Programming (AOP):** Implemented method interception via `MethodInterceptor` protocol and `@intercepted_by` decorator, using a dynamic proxy (`UnifiedComponentProxy`) (ADR-005).
+* **Eager Startup Validation:** Added fail-fast validation during `init()` to detect missing dependencies and configuration errors before runtime (ADR-006).
+* **Built-in Event Bus:** Included an asynchronous, in-process event bus (`EventBus`, `@subscribe`, `AutoSubscriberMixin`) for decoupled communication (ADR-007).
+* **Explicit Circular Dependency Handling:** Implemented detection and fail-fast for circular dependencies, requiring explicit resolution patterns (ADR-008).
+* **Unified Decorator API:** Consolidated component metadata into parameterized decorators (`@component`, `@factory`, `@provides`), removing older stacked decorators (ADR-009).
 
-* **`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.
+### ✨ Added
 
-### Internal 🔧
+* Core registration decorators: `@component`, `@factory`, `@provides`.
+* Configuration decorators: `@configuration` (flat key-value) and `@configured` (tree-based).
+* Lifecycle decorators: `@configure`, `@cleanup`.
+* AOP decorator: `@intercepted_by`.
+* Event bus decorator: `@subscribe`.
+* Health check decorator: `@health`.
+* Async resolution: `container.aget()` and `__ainit__` convention.
+* Async cleanup: `container.cleanup_all_async()`.
+* Qualifier support (`Qualifier` class) for list injection (`Annotated[List[Type], Qualifier(...)]`).
+* Support for `lazy=True` parameter for deferred component instantiation.
+* Conditional binding parameters (`conditional_profiles`, `conditional_require_env`, `conditional_predicate`).
+* Fallback binding parameters (`on_missing_selector`, `on_missing_priority`).
+* Primary selection parameter (`primary=True`).
+* Testing support via `init(overrides={...})` and `init(profiles=(...))`.
+* Container context management (`as_current`, `get_current`, `shutdown`, `all_containers`).
+* Scope management API (`activate_scope`, `deactivate_scope`, `scope` context manager).
+* Configuration sources: `EnvSource`, `FileSource` (flat); `JsonTreeSource`, `YamlTreeSource`, `DictSource` (tree).
+* Protocols for extension: `MethodInterceptor`, `ContainerObserver`, `ScopeProtocol`, `ConfigSource`, `TreeSource`.
 
-* 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).
+### ⚠️ Breaking Changes
 
-### Notes 📝
+* Complete redesign compared to any prior internal/unreleased versions. APIs are not backward compatible.
+* Requires Python 3.10+.
 
-* Fully backward compatible.
-* This patch release focuses on decorator correctness and configuration flexibility improvements.
+### 📚 Docs
+
+* Established new documentation structure including ADRs, Architecture, User Guide, Advanced Features, Cookbook, Integrations, and API Reference.
+
+### 🧪 Testing
+
+* Added comprehensive test suite covering core features, async behavior, AOP, configuration, scopes, and error handling.
+* Introduced patterns for testing with overrides and profiles.
 
 ---
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.0.2
+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.2 → 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,
@@ -51,6 +52,7 @@ __all__ = [
     "SerializationError",
     "ValidationError",
     "InvalidBindingError",
+    "AsyncResolutionError",
     "EventBusClosedError",
     "component",
     "factory",

pico_ioc-2.0.3/src/pico_ioc/_version.py

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

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

@@ -9,7 +9,6 @@ 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, Mapping
 from .constants import LOGGER, PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
 from .exceptions import (
-    ProviderNotFoundError,
     CircularDependencyError,
     ScopeError,
     ConfigurationError,
@@ -409,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
@@ -574,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.2 → 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.2 → 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.2 → 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.2 → 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.2
+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.2 → 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.2 → 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.2/src/pico_ioc/_version.py

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