feat: add provider.derive(fn) to inject a value computed from another provider (#733)

settings.derive(lambda s: s.db_dsn) is a provider of fn(value). Type
checkers infer s from the source. It is never cached, has no scope of its
own and resolves at its source's effective scope, so it works inline in
kwargs in any group and an override of the source reaches it. An exception
raised by fn propagates unchanged, with a note naming the derived provider.

The class is private (_Derived) and lives in providers/abstract.py,
because the derive method on AbstractProvider needs it, and a separate
module would create an import cycle.

Closes #730

Author: lesnik512

CONTEXT.md

@@ -23,9 +23,9 @@ One band in the container hierarchy.
 _Avoid_: lifetime, layer
 
 **Effective scope**:
-The band a provider actually resolves in, once any redirection to another provider is followed. The
-same as the provider's own scope unless it redirects, where the provider at the end of the chain
-governs.
+The band a provider actually resolves in, once any redirection to another provider, or a derived
+provider's source, is followed. The same as the provider's own scope unless it redirects or derives,
+where the provider at the end of the chain governs.
 _Avoid_: terminal scope
 
 **Group**:
@@ -45,6 +45,11 @@ _Avoid_: mock, patch
 The type a provider is registered under.
 _Avoid_: registered type, return type
 
+**Derived provider**:
+A provider of a function of one source provider's value, built by `provider.derive(fn)`. Never
+cached, with its source's effective scope.
+_Avoid_: computed (implies caching), selector (picks a provider by key in other libraries), attribute getter
+
 **Reference-only provider**:
 A provider with no bound type, resolvable only by passing the provider itself.
 _Avoid_: unbound provider, anonymous provider

docs/migration/from-dependency-injector.md

@@ -82,7 +82,7 @@ Use this table as the index for the rest of the guide. "No direct equivalent" ro
 | `Delegate` and the `Delegated*` providers (`DelegatedFactory`, `DelegatedSingleton`, ...) | A creator parameter annotated `Container`, resolving the provider later | [§4](#4-migrate-the-dependency-graph) |
 | `Selector` | No direct equivalent | [§11](#11-no-direct-equivalent) |
 | `Aggregate` / `FactoryAggregate` | No direct equivalent | [§11](#11-no-direct-equivalent) |
-| `.provided` (attribute / item / method-call access on a provider) | No direct equivalent | [§11](#11-no-direct-equivalent) |
+| `.provided` (attribute / item / method-call access on a provider) | `provider.derive(fn)`, e.g. `provider.derive(lambda value: value.attr)` | [Derived values](../providers/factories.md#derived-values) |
 | `@inject` + `Provide[...]` + `container.wire(modules=[...])` (web) | `FromDI(T)` from the framework integration | [§6](#6-wiring-replacement), [§8](#8-framework-integration-and-routes) |
 | `@inject` + `Provide[...]` + `container.wire(modules=[...])` (non-web) | Explicit `container.resolve(T)` | [§6](#6-wiring-replacement) |
 | `DeclarativeContainer` | `Group` (schema) + `Container(groups=[...])` (runtime), checked with `.validate()` | [§2](#2-key-conceptual-shifts) |
@@ -358,7 +358,6 @@ A handful of `dependency-injector` features have no direct port. Workarounds:
 - For `ThreadLocalSingleton`, register an uncached `Factory` whose creator reads the object from a module-level `threading.local()` and creates and stores it there on a thread's first call. A cached `Factory` can't do this, because it caches one object for the whole container.
 - For `Selector`, write a creator function that takes whatever the selector depended on and returns the chosen object. If the choice is static (e.g. one implementation per environment), `Alias` may be cleaner.
 - For `Aggregate` / `FactoryAggregate`, resolve each candidate provider individually (by type or by reference) and dispatch on the key yourself in a small creator function, rather than injecting the whole aggregate object.
-- For `.provided` (attribute / item / method-call access on a provider, e.g. `service.provided.value`), resolve the parent inside the consuming creator and access the attribute, item, or method result there, or expose a dedicated `Factory` whose creator returns just that piece.
 - `modern-di` has no general-purpose injection decorator to replace `@inject` + `Provide[...]` on non-framework functions. Call `container.resolve(T)` explicitly at the call site, or expose the function through a framework integration and use `FromDI(T)`.
 - Providers are not partially applied callables. In `dependency-injector`, calling a provider with extra arguments (`container.some_factory(extra_arg)`) merges them with the declared ones for that one call. `modern-di`'s `resolve()` and `resolve_provider()` take no arguments, so every creator argument must come from its type, from `kwargs`, or from a default. Move a static value into `kwargs=`. For a value that varies per call site, use a `ContextProvider` set on the container you resolve from, or a deeper-scoped dependency.
 

docs/migration/from-that-depends.md

@@ -73,7 +73,7 @@ Use this table as the index for the rest of the guide.
 | `List` | `providers.Factory` with a creator that returns a list | [§4](#4-migrate-the-dependency-graph) |
 | `Dict` | `providers.Factory` with a creator that returns a dict | [§4](#4-migrate-the-dependency-graph) |
 | `Selector` | No direct equivalent | [§9](#9-no-direct-equivalent) |
-| `AttrGetter` (`provider.attr`) | No direct equivalent | [§9](#9-no-direct-equivalent) |
+| `AttrGetter` (`provider.attr`) | `provider.derive(lambda value: value.attr)` | [Derived values](../providers/factories.md#derived-values) |
 | `ThreadLocalSingleton` | No direct equivalent | [§9](#9-no-direct-equivalent) |
 | `State` | `ContextProvider` + `set_context` | [§5](#5-context-resources-and-request-scope) |
 | `provider.bind(T)` | `providers.Factory(..., bound_type=T)`; add an `Alias` per extra type | [§4](#4-migrate-the-dependency-graph) |
@@ -367,7 +367,6 @@ On routes, `FromDI(T)` replaces both `fastapi.Depends(Container.provider)` and `
 A handful of `that-depends` features have no direct port. Workarounds:
 
 - For `Selector`, write a creator function that takes whatever the selector depended on and returns the chosen object. If the choice is static (e.g. one implementation per environment), `Alias` may be cleaner.
-- For `AttrGetter` (`provider.attr` syntax), resolve the parent inside the consuming creator and access the attribute there, or expose a dedicated `Factory` whose creator returns the attribute.
 - For `ThreadLocalSingleton`, register an uncached `Factory` whose creator reads the object from a module-level `threading.local()` and creates and stores it there on a thread's first call. A cached `Factory` can't do this, because it caches one object for the whole container.
 - `modern-di` has no general-purpose injection decorator to replace `@inject` + `Provide[...]` on non-framework functions. Call `container.resolve(T)` explicitly at the call site, or expose the function through a framework integration and use `FromDI(T)`.
 - For `BaseContainer.resolve(func)` and `resolver(func)`, which call `func` with its parameters filled by name, register `func` as a `Factory` with `bound_type=None` and call `container.resolve_provider(...)` on it. Its parameters are then wired by type, not by name.

docs/providers/factories.md

@@ -110,6 +110,8 @@ Values for creator parameters, by name. A parameter named in `kwargs` is not wir
 - A plain value is passed as is.
 - A provider is resolved when the factory resolves, and its result is passed. Use it to pick a
   specific provider for one parameter, or to wire arguments under `skip_creator_parsing=True`.
+  To pass a piece of another provider's value, such as one settings field, use
+  [`derive`](#derived-values).
 - A name the creator does not have raises `UnknownFactoryKwargError` when the `Factory` is
   declared.
 
@@ -155,6 +157,59 @@ Without an explicit `bound_type`, `Factory(...)` emits a `UserWarning` saying th
 resolved by type. Pass `bound_type=SomeType` to register it, or `bound_type=None` to confirm it is
 resolved by reference only.
 
+## Derived values
+
+`provider.derive(fn)` returns a provider of `fn(value)`, where `value` is what `provider` resolves
+to. Use it in `kwargs` to pass a field of a settings object without writing a creator function for
+the component:
+
+```python
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class Settings:
+    db_dsn: str = "postgresql://localhost/app"
+    db_pool_size: int = 5
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class Database:
+    dsn: str
+    pool_size: int
+
+
+class AppDependencies(Group):
+    settings = providers.Factory(Settings, cache=True)
+    database = providers.Factory(
+        Database,
+        kwargs={
+            "dsn": settings.derive(lambda s: s.db_dsn),
+            "pool_size": settings.derive(lambda s: s.db_pool_size),
+        },
+        cache=True,
+    )
+
+
+container = Container(groups=[AppDependencies])
+container.override(AppDependencies.settings, Settings(db_dsn="postgresql://test/app"))
+assert container.resolve(Database).dsn == "postgresql://test/app"
+```
+
+Type checkers infer `s` from `settings`, so mypy, pyright and ty all flag `s.db_dns`. `fn` can read
+an attribute or an item, or call a method, and `derive` calls chain.
+
+A derived provider:
+
+- Has no scope of its own. It resolves at its source's scope, and a group's default scope does not
+  apply to it, so it is valid in `kwargs` in any group. `validate()` checks the consuming factory
+  against the source's scope.
+- Is never cached: `fn` runs on every resolve, so an override of the source always reaches it. If
+  the value is worth caching, give it a `Factory`.
+- Is not registered under any type. Use it in `kwargs`, or resolve it with
+  `container.resolve_provider`.
+- Can be overridden itself, like any provider.
+
+An exception raised by `fn` propagates unchanged, with a note naming the derived provider and the
+line `fn` is defined on.
+
 ## Resolution behavior
 
 ### Union type parameters
@@ -269,3 +324,4 @@ assert connection is container.resolve(Connection)  # and is cached now
 - [Lifecycle](lifecycle.md): finalizers, closing, and `validate()`.
 - [Scopes](scopes.md): which container caches an instance.
 - [Alias](alias.md): making one type resolve to another type's provider, such as a `Protocol` to its implementation.
+- [Testing with overrides](../recipes/testing-overrides.md): replacing a settings object in tests.

modern_di/dependency_graph.py

@@ -11,7 +11,7 @@
 
 from modern_di import exceptions
 from modern_di.exceptions.rendering import provider_step
-from modern_di.providers.abstract import AbstractProvider
+from modern_di.providers.abstract import AbstractProvider, _Derived
 from modern_di.providers.alias import Alias
 from modern_di.providers.container_provider import container_provider
 from modern_di.providers.factory import Factory
@@ -88,6 +88,8 @@ def dependencies_of(
                 source_type=source_type, reference_only_providers=reference_only_sources(source_type, registry)
             )
         return {"source": source}
+    if type(provider) is _Derived:
+        return {"source": provider._source}  # noqa: SLF001
     return {}
 
 
@@ -110,9 +112,19 @@ def terminal_chain(
     return chain
 
 
+def scope_chain(
+    provider: "AbstractProvider[typing.Any]", registry: "ProvidersRegistry"
+) -> "list[AbstractProvider[typing.Any]]":
+    """Extend ``terminal_chain`` through derived providers to their sources; the last one owns the scope."""
+    chain = terminal_chain(provider, registry)
+    while type(chain[-1]) is _Derived:
+        chain += terminal_chain(chain[-1]._source, registry)  # noqa: SLF001
+    return chain
+
+
 def effective_scope(provider: "AbstractProvider[typing.Any]", registry: "ProvidersRegistry") -> enum.IntEnum:
-    """Return the scope a provider actually resolves at: its terminal's, once redirects are followed."""
-    return terminal_chain(provider, registry)[-1].scope
+    """Return the scope a provider actually resolves at: that of the last provider in its `scope_chain`."""
+    return scope_chain(provider, registry)[-1].scope
 
 
 def redirect_hops(
@@ -210,7 +222,7 @@ def collect_errors(registry: "ProvidersRegistry") -> list[Exception]:
     for event in walk(roots=roots, registry=registry):
         if type(event) is Edge:
             parent, name, dep = event
-            dependency_chain = terminal_chain(dep, registry)
+            dependency_chain = scope_chain(dep, registry)
             if dependency_chain[-1] is container_provider:
                 continue
             dependency_scope = dependency_chain[-1].scope

modern_di/exceptions/resolution.py

@@ -18,6 +18,12 @@
     from modern_di.providers.abstract import AbstractProvider
 
 
+def derived_note(step: ResolutionStep) -> str:
+    """Return the note for an exception raised by the function of the derived provider drawn as ``step``."""
+    label = f"{step.name} ({step.location})" if step.location else step.name
+    return f"raised by the function of {label}"
+
+
 class ResolutionError(ModernDIError):
     """Base class for errors raised while resolving a provider.
 

modern_di/providers/abstract.py

@@ -29,7 +29,7 @@ class AbstractProvider(typing.Generic[types.T_co]):
     )
 
     _takes_group_scope: typing.ClassVar[bool] = True
-    """Whether a Group-level default scope applies. False when the effective scope is derived."""
+    """Whether a Group-level default scope applies. False when the effective scope comes from another provider."""
 
     def __init_subclass__(cls, **kwargs: object) -> None:
         if cls.__module__.partition(".")[0] != "modern_di":
@@ -46,16 +46,19 @@ def __init__(
         scope: enum.IntEnum | types.UnsetType,
         bound_type: type | types.UnsetType | None,
         inferred_bound_type: type | None = None,
+        call_depth: int = 2,
     ) -> None:
-        """Set the shared state; an unset ``bound_type`` falls back to ``inferred_bound_type``."""
+        """Set the shared state; an unset ``bound_type`` falls back to ``inferred_bound_type``.
+
+        ``call_depth`` is the frame, counted from here, of the user code that built the provider.
+        """
         self._explicit_scope: enum.IntEnum | None = scope if isinstance(scope, enum.IntEnum) else None
         self._group_claim: tuple[enum.IntEnum, str] | None = None
         self._registered = False
         self._bound_type = inferred_bound_type if isinstance(bound_type, types.UnsetType) else bound_type
         self._provider_id = next(_provider_id_counter)
         self._declared_as: str | None = None
-        # Frame 2 is whoever called the concrete provider's __init__, which calls this one directly.
-        caller = sys._getframe(2)  # noqa: SLF001
+        caller = sys._getframe(call_depth)  # noqa: SLF001
         self._call_module: str | None = caller.f_globals.get("__name__")
         self._call_line = caller.f_lineno
 
@@ -127,3 +130,40 @@ def display_name(self) -> str:
     def definition_site(self) -> str | None:
         """``module:line`` of the provider's declaration when known; None by default (no creator)."""
         return None
+
+    def derive(self, fn: typing.Callable[[types.T_co], types.T], /) -> "AbstractProvider[types.T]":
+        """Return a provider of ``fn(value)``, where ``value`` is what this provider resolves to.
+
+        The derived provider is never cached and has no scope of its own: it resolves at this
+        provider's scope, so it is valid in ``kwargs`` of any group, and an override of this provider
+        reaches it. It is not registered under any type. An exception raised by ``fn`` propagates
+        unchanged, with a note naming the derived provider.
+        """
+        return _Derived(self, fn)
+
+
+class _Derived(AbstractProvider[types.T_co]):
+    __slots__ = ("_fn", "_source")
+
+    _takes_group_scope = False
+
+    def __init__(self, source: AbstractProvider[typing.Any], fn: typing.Callable[[typing.Any], types.T_co]) -> None:
+        super().__init__(scope=types.UNSET, bound_type=None, call_depth=3)
+        self._source = source
+        self._fn = fn
+
+    def __repr__(self) -> str:
+        return f"{self.display_name}({self._fn!r})"
+
+    @property
+    def display_name(self) -> str:
+        return f"{self._source.display_name}.derive"
+
+    @property
+    def definition_site(self) -> str | None:
+        """``fn``'s declaration site as ``module:line``; else the ``derive`` call site."""
+        module = getattr(self._fn, "__module__", None)
+        code = getattr(self._fn, "__code__", None)
+        if module is None or code is None:
+            return self._call_site
+        return f"{module}:{code.co_firstlineno}"

modern_di/resolver_compiler.py

@@ -23,9 +23,10 @@
 
 from modern_di import exceptions, types
 from modern_di.cache import CacheItem
-from modern_di.dependency_graph import redirect_hops, reference_only_sources, terminal_chain
+from modern_di.dependency_graph import effective_scope, redirect_hops, reference_only_sources, terminal_chain
 from modern_di.exceptions.rendering import UNKNOWN_SCOPE, provider_step
-from modern_di.providers.abstract import AbstractProvider
+from modern_di.exceptions.resolution import derived_note
+from modern_di.providers.abstract import AbstractProvider, _Derived
 from modern_di.providers.alias import Alias
 from modern_di.providers.container_provider import container_provider
 from modern_di.providers.context_provider import ContextProvider
@@ -52,6 +53,8 @@ def compile_resolver(provider: "AbstractProvider[typing.Any]", registry: "Provid
         return _compile_factory(provider, registry)
     if type(provider) is Alias:
         return _compile_alias(provider, registry)
+    if type(provider) is _Derived:
+        return _compile_derived(provider, registry)
     if provider is container_provider:
         return _resolve_to_container
     if type(provider) is ContextProvider:
@@ -289,6 +292,29 @@ def resolve(_: "Container") -> typing.Any:
     return resolve
 
 
+def _compile_derived(d: "_Derived[typing.Any]", registry: "ProvidersRegistry") -> "Resolver":
+    """Compile to ``fn`` over the source's resolver; the source navigates to its own scope."""
+    source = d._source
+    fn = d._fn
+    source_resolver = registry.resolver_for(source)
+    step = provider_step(d, effective_scope(d, registry))
+    hops = redirect_hops(source, registry)
+
+    def resolve(container: "Container") -> typing.Any:
+        try:
+            value = source_resolver(container)
+        except exceptions.ResolutionError as exc:
+            exc._prepend_step(step, *hops)
+            raise
+        try:
+            return fn(value)
+        except Exception as exc:
+            exc.add_note(derived_note(step))
+            raise
+
+    return resolve
+
+
 def _resolve_to_container(container: "Container") -> typing.Any:
     return container