Add mapping on aggregates (#133)

* Add Mapping[Hashable, T] collection injection

* Document and test Mapping[Hashable, T]

Author: Stuckya

docs/pages/interfaces.md

@@ -212,6 +212,67 @@ class CacheReporter:
 
 `Sequence[T]` includes the default implementation, if present, plus any qualified implementations in registration order.
 
+## Inject Implementations by Qualifier
+
+When you want every implementation keyed by its qualifier, request them at once with `collections.abc.Mapping[Hashable, T]`.
+
+```python
+from collections.abc import Hashable, Mapping
+from dataclasses import dataclass
+from typing import Protocol
+from wireup import create_sync_container, injectable
+
+
+class Cache(Protocol):
+    def source(self) -> str: ...
+
+
+@injectable(as_type=Cache)
+class InMemoryCache:
+    def source(self) -> str:
+        return "memory"
+
+
+@injectable(as_type=Cache, qualifier="redis")
+class RedisCache:
+    def source(self) -> str:
+        return "redis"
+
+
+@injectable
+@dataclass
+class CacheRouter:
+    caches: Mapping[Hashable, Cache]
+
+    def default(self) -> Cache:
+        return self.caches[None]
+```
+
+`Mapping[Hashable, Cache]` includes every implementation, keyed by its qualifier. The unqualified default is keyed under `None`.
+
+!!! note "Mapping Type"
+
+    Only `collections.abc.Mapping[Hashable, T]` is supported. Requesting `typing.Mapping[K, V]` raises
+    `UnknownServiceRequestedError` with a hint pointing at `collections.abc.Mapping[Hashable, T]`.
+
+    If you want to register your own factory for a `Mapping[Hashable, T]` (e.g., with custom keys or transformation
+    logic), wrap it in a `NewType`:
+
+    ```python
+    from collections.abc import Hashable, Mapping
+    from typing import Annotated, NewType
+    from wireup import Inject, injectable
+
+    CacheMap = NewType("CacheMap", Mapping[Hashable, Cache])
+
+
+    @injectable
+    def make_cache_map(
+        default: Cache,
+        redis: Annotated[Cache, Inject(qualifier="redis")],
+    ) -> CacheMap:
+        return CacheMap({None: default, "redis": redis})
+    ```
 
 ## `as_type` with Optional Types
 

test/unit/test_container_collection_injection.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
 import typing
-from collections.abc import Sequence
+from collections.abc import Hashable, Mapping, Sequence
 from dataclasses import dataclass
-from typing import Optional, Protocol
+from typing import Annotated, NewType, Optional, Protocol
 
 import pytest
-from wireup import Injected, create_sync_container, inject_from_container, injectable
+from wireup import Inject, Injected, create_sync_container, inject_from_container, injectable
 from wireup._annotations import InjectableDeclaration
 from wireup.errors import UnknownServiceRequestedError, WireupError
 from wireup.ioc.registry import ContainerRegistry
@@ -178,3 +178,190 @@ class Consumer:
         match=r"uses typing\.Sequence\[.*Cache.*\], but Wireup collection injection requires collections\.abc\.Sequence\[.*Cache.*\]",  # noqa: E501
     ):
         create_sync_container(injectables=[MemoryCache, RedisCache, Consumer])
+
+
+def test_injects_collection_mapping_for_as_type() -> None:
+    container = create_sync_container(injectables=[MemoryCache, RedisCache])
+
+    @inject_from_container(container)
+    def handler(caches: Injected[Mapping[Hashable, Cache]]) -> dict[Hashable, str]:
+        return {key: cache.source() for key, cache in caches.items()}
+
+    assert handler() == {None: "memory", "redis": "redis"}
+    assert container.get(Mapping[Hashable, Cache]) is container.get(Mapping[Hashable, Cache])
+
+
+def test_injects_collection_mapping_for_single_implementation() -> None:
+    container = create_sync_container(injectables=[MemoryCache])
+    res = container.get(Mapping[Hashable, Cache])
+
+    assert isinstance(res, dict)
+    assert list(res.keys()) == [None]
+    assert res[None].source() == "memory"
+
+
+def test_default_impl_appears_under_none_key() -> None:
+    container = create_sync_container(injectables=[MemoryCache])
+    res = container.get(Mapping[Hashable, Cache])
+
+    assert res[None].source() == "memory"
+
+
+def test_mapping_works_with_only_qualified_impls() -> None:
+    @injectable(as_type=Cache, qualifier="memory")
+    class QualifiedMemoryCache:
+        def source(self) -> str:
+            return "memory"
+
+    container = create_sync_container(injectables=[QualifiedMemoryCache, RedisCache])
+    res = container.get(Mapping[Hashable, Cache])
+
+    assert set(res.keys()) == {"memory", "redis"}
+    assert None not in res
+
+
+def test_mapping_supports_non_string_qualifiers() -> None:
+    @injectable(as_type=Cache, qualifier=0)
+    class ZeroCache:
+        def source(self) -> str:
+            return "zero"
+
+    @injectable(as_type=Cache, qualifier=1)
+    class OneCache:
+        def source(self) -> str:
+            return "one"
+
+    container = create_sync_container(injectables=[ZeroCache, OneCache])
+    res = container.get(Mapping[Hashable, Cache])
+
+    assert res[0].source() == "zero"
+    assert res[1].source() == "one"
+
+
+def test_mapping_lifetime_is_smallest_member_lifetime() -> None:
+    @injectable(as_type=Cache, qualifier="default")
+    class DefaultCache:
+        def source(self) -> str:
+            return "default"
+
+    @injectable(as_type=Cache, qualifier="scoped", lifetime="scoped")
+    class ScopedCache:
+        def source(self) -> str:
+            return "scoped"
+
+    @injectable
+    @dataclass
+    class Consumer:
+        caches: Mapping[Hashable, Cache]
+
+    with pytest.raises(
+        WireupError,
+        match="depends on an injectable with a 'scoped' lifetime which is not supported",
+    ):
+        create_sync_container(injectables=[DefaultCache, ScopedCache, Consumer])
+
+
+def test_can_override_mapping_directly() -> None:
+    container = create_sync_container(injectables=[MemoryCache, RedisCache])
+    override_map = {"override": RedisCache()}
+
+    assert set(container.get(Mapping[Hashable, Cache]).keys()) == {None, "redis"}
+    with container.override.injectable(Mapping[Hashable, Cache], new=override_map):
+        assert container.get(Mapping[Hashable, Cache]) is override_map
+    assert set(container.get(Mapping[Hashable, Cache]).keys()) == {None, "redis"}
+
+
+def test_explicit_mapping_registration_takes_precedence_and_warns() -> None:
+    mapping = {"custom": RedisCache()}
+
+    @injectable
+    def make_custom_mapping() -> Mapping[Hashable, Cache]:
+        return mapping
+
+    with pytest.warns(FutureWarning, match=r"Mapping\[Hashable, T\] is reserved for Wireup collection injection"):
+        container = create_sync_container(injectables=[MemoryCache, make_custom_mapping])
+
+    assert container.get(Mapping[Hashable, Cache]) is mapping
+
+
+def test_injects_collection_mapping_when_registration_key_comes_from_factory_return_type() -> None:
+    @injectable
+    def make_default_cache() -> Cache:
+        return MemoryCache()
+
+    @injectable(qualifier="redis")
+    def make_redis_cache() -> Cache:
+        return RedisCache()
+
+    container = create_sync_container(injectables=[make_default_cache, make_redis_cache])
+    res = container.get(Mapping[Hashable, Cache])
+
+    assert isinstance(res, dict)
+    assert {key: cache.source() for key, cache in res.items()} == {None: "memory", "redis": "redis"}
+
+
+def test_internal_extend_does_not_create_nested_mapping_collections() -> None:
+    registry = ContainerRegistry(impls=[InjectableDeclaration(obj=MemoryCache, lifetime="singleton")])
+
+    @injectable
+    class ExtraService:
+        pass
+
+    registry.extend(impls=[InjectableDeclaration(obj=ExtraService, lifetime="singleton")])
+
+    assert Mapping[Hashable, Mapping[Hashable, MemoryCache]] not in registry.impls
+
+
+def test_mixed_real_and_optional_compat_registrations_only_include_real_members_in_mapping() -> None:
+    @injectable
+    def make_optional_default_cache() -> Cache | None:
+        return None
+
+    @injectable(qualifier="redis")
+    def make_redis_cache() -> Cache:
+        return RedisCache()
+
+    container = create_sync_container(injectables=[make_optional_default_cache, make_redis_cache])
+
+    assert container.get(Mapping[Hashable, Cache]) == {"redis": container.get(Cache, qualifier="redis")}
+
+
+def test_typing_mapping_is_not_registered() -> None:
+    container = create_sync_container(injectables=[MemoryCache, RedisCache])
+
+    with pytest.raises(
+        UnknownServiceRequestedError,
+        match=r"Wireup collection injection uses collections\.abc\.Mapping\[.*Cache.*\], not typing\.Mapping\[.*Cache.*\]",  # noqa: E501
+    ):
+        container.get(typing.Mapping[str, Cache])
+
+
+def test_typing_mapping_dependency_raises_helpful_error() -> None:
+    @injectable
+    @dataclass
+    class Consumer:
+        caches: typing.Mapping[str, Cache]
+
+    with pytest.raises(
+        WireupError,
+        match=r"uses typing\.Mapping\[.*Cache.*\], but Wireup collection injection requires collections\.abc\.Mapping\[.*Cache.*\]",  # noqa: E501
+    ):
+        create_sync_container(injectables=[MemoryCache, RedisCache, Consumer])
+
+
+CacheMap = NewType("CacheMap", Mapping[Hashable, Cache])
+
+
+def test_newtype_over_mapping_registers_as_distinct_collection() -> None:
+    @injectable
+    def make_cache_map(
+        default: Cache,
+        redis: Annotated[Cache, Inject(qualifier="redis")],
+    ) -> CacheMap:
+        return CacheMap({None: default, "redis": redis})
+
+    container = create_sync_container(injectables=[MemoryCache, RedisCache, make_cache_map])
+    res = container.get(CacheMap)
+
+    assert isinstance(res, dict)
+    assert {key: cache.source() for key, cache in res.items()} == {None: "memory", "redis": "redis"}

test/unit/test_container_creation.py

@@ -80,6 +80,26 @@ class Bar:
         wireup.create_sync_container(injectables=[FooImpl, Bar])
 
 
+def test_checks_typing_mapping_dependency_uses_helpful_error() -> None:
+    class Foo(Protocol): ...
+
+    @wireup.injectable(as_type=Foo)
+    class FooImpl:
+        pass
+
+    @wireup.injectable
+    @dataclass
+    class Bar:
+        foo: typing.Mapping[str, Foo]
+
+    with pytest.raises(
+        WireupError,
+        match=r"Parameter 'foo' of Type test\.unit\.test_container_creation\.Bar uses typing\.Mapping\[.*Foo.*\], "
+        r"but Wireup collection injection requires collections\.abc\.Mapping\[.*Foo.*\]\.",
+    ):
+        wireup.create_sync_container(injectables=[FooImpl, Bar])
+
+
 def test_lifetimes_match() -> None:
     @wireup.injectable(lifetime="scoped")
     class ScopedService: ...

wireup/errors.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import sys
+from collections.abc import Hashable
+from collections.abc import Mapping as AbcMapping
 from collections.abc import Sequence as AbcSequence
 from typing import TYPE_CHECKING, Any
 
@@ -24,6 +26,20 @@ def try_get_wireup_sequence_replacement(type_hint: Any) -> Any | None:
     return AbcSequence[args] if args else AbcSequence  # type:ignore[valid-type]
 
 
+def try_get_wireup_mapping_replacement(type_hint: Any) -> Any | None:
+    """Return collection type replacement for typing.Mapping[K, V] if applicable."""
+    if getattr(type_hint, "__module__", None) != "typing":
+        return None
+
+    if get_origin(type_hint) is not AbcMapping:
+        return None
+
+    args = get_args(type_hint)
+    if not args:
+        return AbcMapping
+    return AbcMapping[Hashable, args[1]]  # type:ignore[valid-type]
+
+
 class WireupError(Exception):
     """Base type for all exceptions raised by wireup."""
 
@@ -104,6 +120,13 @@ def __init__(self, klass: Any, qualifier: Qualifier | None = None) -> None:
             )
             return
 
+        if suggested_replacement_type := try_get_wireup_mapping_replacement(klass):
+            super().__init__(
+                f"Cannot create unknown injectable {format_name(klass, qualifier)}. "
+                f"Wireup collection injection uses {suggested_replacement_type!r}, not {klass!r}."
+            )
+            return
+
         msg = (
             f"Cannot create unknown injectable {format_name(klass, qualifier)}. "
             "Make sure it is registered with the container."