feat: allow manual override of dependencies

This change introduces the ability to manually override dependencies in `fastapi-injectable`. Any arguments explicitly passed to an `@injectable` function will now take priority over the dependency injection system.

This is particularly useful for:
- Mocking dependencies in tests.
- Providing values directly in CLI tools.

This change also fixes a bug where `fastapi-injectable` would still resolve a dependency even if it was explicitly provided as an argument, causing unexpected behavior.

Fixes: #133

Author: JasperSui

README.md

@@ -69,12 +69,13 @@ print(result) # Output: 'data'
 
 ## Key Features
 
-1. **Flexible Injection**: Use decorators, function wrappers, or utility functions.
-2. **Full Async Support**: Works with both sync and async code.
-3. **Resource Management**: Built-in cleanup for dependencies.
-4. **Dependency Caching**: Optional caching for better performance.
-5. **Graceful Shutdown**: Automatic cleanup on program exit.
-6. **Event Loop Management**: Control the event loop to ensure the objects created by `fastapi-injectable` are executed in the right loop.
+1. **Basic Injection**: Use decorators, function wrappers, or utility functions.
+2. **Manual Overrides**: Explicit arguments you pass always take priority over injected dependencies (great for tests and mocks).
+3. **Full Async Support**: Works with both sync and async code.
+4. **Resource Management**: Built-in cleanup for dependencies.
+5. **Dependency Caching**: Optional caching for better performance.
+6. **Graceful Shutdown**: Automatic cleanup on program exit.
+7. **Event Loop Management**: Control the event loop to ensure the objects created by `fastapi-injectable` are executed in the right loop.
 
 ## Overview
 
@@ -148,6 +149,42 @@ result = get_injected_obj(process_data)
 print(result) # Output: 'data'
 ```
 
+### Manual Overrides
+
+Sometimes you want to use FastAPI’s dependency injection system, but still explicitly pass certain arguments yourself.
+
+For example, in tests you may want to supply a mock instead of the default dependency, or in CLI tools you may want to provide a value directly.
+
+`fastapi-injectable` makes this possible by allowing manual overrides: any arguments you pass will take priority over injected dependencies.
+
+```python
+from typing import Annotated
+from fastapi import Depends
+from fastapi_injectable import get_injected_obj, injectable
+
+class Database:
+    def query(self) -> str:
+        return "real data"
+
+def get_db() -> Database:
+    return Database()
+
+@injectable
+def process_data(db: Annotated[Database, Depends(get_db)]) -> str:
+    return db.query()
+
+# Normal usage – resolved through DI
+print(process_data())
+# Output: "real data"
+
+# Override dependency manually (great for tests)
+mock_db = Database()
+mock_db.query = lambda: "mock data"
+
+print(process_data(db=mock_db)) # Explicitly pass the mock dependency
+# Output: "mock data"
+```
+
 ### Generator Dependencies with Cleanup
 
 When working with generator dependencies that require cleanup (like database connections or file handles), `fastapi-injectable` provides built-in support for controlling dependency lifecycles and proper resource management with error handling.

src/fastapi_injectable/decorator.py

@@ -125,18 +125,20 @@ def decorator(
 
         @wraps(target)
         async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-            dependencies = await resolve_dependencies(func=target, use_cache=use_cache)
+            dependencies = await resolve_dependencies(func=target, use_cache=use_cache, provided_kwargs=kwargs)
             return await cast("Callable[..., Coroutine[Any, Any, T]]", target)(*args, **{**dependencies, **kwargs})
 
         @wraps(target)
         async def async_gen_wrapper(*args: P.args, **kwargs: P.kwargs) -> AsyncGenerator[T, Any]:
-            dependencies = await resolve_dependencies(func=target, use_cache=use_cache)
+            dependencies = await resolve_dependencies(func=target, use_cache=use_cache, provided_kwargs=kwargs)
             async for x in cast("Callable[..., AsyncGenerator[T, Any]]", target)(*args, **{**dependencies, **kwargs}):
                 yield x
 
         @wraps(target)
         def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-            dependencies = run_coroutine_sync(resolve_dependencies(func=target, use_cache=use_cache))
+            dependencies = run_coroutine_sync(
+                resolve_dependencies(func=target, use_cache=use_cache, provided_kwargs=kwargs)
+            )
             return cast("Callable[..., T]", target)(*args, **{**dependencies, **kwargs})
 
         if is_async_generator:

src/fastapi_injectable/main.py

@@ -27,7 +27,10 @@ def _get_app() -> FastAPI | None:
 
 
 async def resolve_dependencies(
-    func: Callable[P, T] | Callable[P, Awaitable[T]], *, use_cache: bool = True
+    func: Callable[P, T] | Callable[P, Awaitable[T]],
+    *,
+    use_cache: bool = True,
+    provided_kwargs: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Resolve dependencies for the given function using FastAPI's dependency injection system.
 
@@ -38,18 +41,24 @@ async def resolve_dependencies(
         func: The function for which dependencies need to be resolved. It can be a synchronous
             or asynchronous callable.
         use_cache: Whether to use a cache for dependency resolution. Defaults to True.
+        provided_kwargs: Explicit kwargs passed by the caller (these override DI).
 
     Returns:
         A dictionary mapping argument names to resolved dependency values.
 
     Notes:
         - A fake HTTP request is created to mimic FastAPI's request-based dependency resolution.
     """
+    provided_kwargs = provided_kwargs or {}
     root_dep = get_dependant(path="command", call=func)
 
     # Get names of actual dependency (Depends()) parameters
     dependency_names = {param.name for param in root_dep.dependencies if param.name}
 
+    # Drop dependencies that are already satisfied by provided kwargs
+    effective_dependencies = [dep for dep in root_dep.dependencies if dep.name not in provided_kwargs]
+    root_dep.dependencies = effective_dependencies
+
     fake_request_scope: dict[str, Any] = {
         "type": "http",
         "headers": [],
@@ -59,7 +68,7 @@ async def resolve_dependencies(
     if app is not None:
         fake_request_scope["app"] = app
     fake_request = Request(fake_request_scope)
-    root_dep.call = cast(Callable[..., Any], root_dep.call)
+    root_dep.call = cast("Callable[..., Any]", root_dep.call)
     async_exit_stack = await async_exit_stack_manager.get_stack(root_dep.call)
     cache = dependency_cache.get() if use_cache else None
     solved_dependency = await solve_dependencies(
@@ -73,6 +82,8 @@ async def resolve_dependencies(
     if cache is not None:
         cache.update(solved_dependency.dependency_cache)
 
-    return {
+    resolved = {
         param_name: value for param_name, value in solved_dependency.values.items() if param_name in dependency_names
     }
+
+    return {**resolved, **provided_kwargs}

test/test_injectable.py

@@ -409,3 +409,77 @@ def get_capital(mayor: Annotated[Mayor | None, Depends(get_mayor)]) -> Capital |
     param = next(iter(sig.parameters.values()))
 
     assert type(param.default).__name__.startswith("Injected")
+
+
+def test_injectable_sync_override_country() -> None:
+    def get_mayor() -> Mayor:
+        return Mayor()
+
+    def get_capital(mayor: Annotated[Mayor, Depends(get_mayor)]) -> Capital:
+        return Capital(mayor)
+
+    @injectable
+    def get_country(capital: Annotated[Capital, Depends(get_capital)]) -> Country:
+        return Country(capital)
+
+    # automatic DI
+    country_injected = get_country()
+    assert isinstance(country_injected, Country)
+    assert isinstance(country_injected.capital, Capital)
+    assert isinstance(country_injected.capital.mayor, Mayor)
+
+    # manual override
+    capital = Capital(Mayor())
+    country_manual = get_country(capital=capital)
+    assert country_manual.capital is capital
+    assert country_manual.capital.mayor is capital.mayor
+
+
+async def test_injectable_async_override_country() -> None:
+    async def get_mayor() -> Mayor:
+        return Mayor()
+
+    async def get_capital(mayor: Annotated[Mayor, Depends(get_mayor)]) -> Capital:
+        return Capital(mayor)
+
+    @injectable
+    async def get_country(capital: Annotated[Capital, Depends(get_capital)]) -> Country:
+        return Country(capital)
+
+    country_injected = await get_country()
+    assert isinstance(country_injected, Country)
+    assert isinstance(country_injected.capital, Capital)
+    assert isinstance(country_injected.capital.mayor, Mayor)
+
+    capital = Capital(Mayor())
+    country_manual = await get_country(capital=capital)
+    assert country_manual.capital is capital
+    assert country_manual.capital.mayor is capital.mayor
+
+
+async def test_injectable_async_gen_override_country() -> None:
+    async def get_mayor() -> Mayor:
+        return Mayor()
+
+    async def get_capital(mayor: Annotated[Mayor, Depends(get_mayor)]) -> Capital:
+        return Capital(mayor)
+
+    @injectable
+    async def get_country(capital: Annotated[Capital, Depends(get_capital)]) -> Country:
+        yield Country(capital)
+
+    country_injected: Country | None = None
+    async for c in get_country():
+        country_injected = c
+        break
+    assert isinstance(country_injected, Country)
+    assert isinstance(country_injected.capital, Capital)
+    assert isinstance(country_injected.capital.mayor, Mayor)
+
+    capital = Capital(Mayor())
+    country_manual: Country | None = None
+    async for c in get_country(capital=capital):
+        country_manual = c
+        break
+    assert country_manual.capital is capital
+    assert country_manual.capital.mayor is capital.mayor

test/test_main.py

@@ -221,3 +221,29 @@ def func() -> None:
     # Verify app was included in request scope
     called_args = mock_solve_dependencies.call_args[1]
     assert called_args["request"].scope["app"] == mock_get_app.return_value
+
+
+async def test_resolve_dependencies_with_provided_kwargs(
+    mock_solve_dependencies: AsyncMock,
+    mock_get_dependant: Mock,
+    mock_dependency_cache: Mock,
+    mock_async_exit_stack_manager: Mock,
+) -> None:
+    dependency_param_name = "dep"
+    mock_dependant_dependency = Mock()
+    mock_dependant_dependency.name = dependency_param_name
+    mock_get_dependant.return_value.dependencies = [
+        mock_dependant_dependency,
+    ]
+    mock_solve_dependencies.return_value = AsyncMock(values={}, dependency_cache={})
+
+    def func(dep: DummyDependency) -> None:
+        return None
+
+    provided_dep = DummyDependency()
+    provided_kwargs = {dependency_param_name: provided_dep}
+    dependencies = await resolve_dependencies(func, provided_kwargs=provided_kwargs)
+
+    assert dependencies == {dependency_param_name: provided_dep}
+    assert mock_get_dependant.return_value.dependencies == []
+    mock_solve_dependencies.assert_awaited_once()