fastapi-injected 0.3.6__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/PKG-INFO +99 -43
  2. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/README.md +98 -42
  3. fastapi_injected-0.4.0/fastapi_injected/__init__.py +33 -0
  4. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_bind.py +16 -23
  5. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_cache.py +3 -3
  6. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_calls.py +36 -20
  7. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_deps_tp.py +36 -1
  8. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_overrides.py +3 -0
  9. fastapi_injected-0.3.6/fastapi_injected/scope.py → fastapi_injected-0.4.0/fastapi_injected/ctx.py +58 -58
  10. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/deps.py +52 -94
  11. fastapi_injected-0.4.0/fastapi_injected/ext.py +23 -0
  12. fastapi_injected-0.3.6/fastapi_injected/_fastapi_lifecycle.py → fastapi_injected-0.4.0/fastapi_injected/fastapi.py +44 -14
  13. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/inject.py +13 -12
  14. fastapi_injected-0.4.0/fastapi_injected/overrides.py +54 -0
  15. fastapi_injected-0.4.0/fastapi_injected/reflect/__init__.py +53 -0
  16. fastapi_injected-0.4.0/fastapi_injected/reflect/_dependant.py +193 -0
  17. fastapi_injected-0.4.0/fastapi_injected/reflect/_openapi.py +48 -0
  18. fastapi_injected-0.4.0/fastapi_injected/reflect/_routes.py +271 -0
  19. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/resolve.py +14 -15
  20. fastapi_injected-0.4.0/fastapi_injected/signature.py +219 -0
  21. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/types.py +12 -1
  22. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/pyproject.toml +1 -1
  23. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/annotations.py +2 -1
  24. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/bind.py +4 -3
  25. fastapi_injected-0.4.0/tests/_typing/ctx.py +67 -0
  26. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/dataclass.py +1 -1
  27. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/inject.py +7 -7
  28. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/injected.py +2 -1
  29. fastapi_injected-0.4.0/tests/_typing/integration.py +41 -0
  30. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/overrides.py +6 -6
  31. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/resolve.py +2 -2
  32. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_bind.py +6 -13
  33. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_body.py +36 -34
  34. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_body_reads.py +11 -8
  35. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_cache.py +14 -14
  36. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_calls.py +23 -12
  37. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_concurrency.py +8 -8
  38. fastapi_injected-0.3.6/tests/test_scope.py → fastapi_injected-0.4.0/tests/test_ctx.py +12 -12
  39. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_dataclass.py +2 -1
  40. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_dependant_cache.py +9 -10
  41. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_fastapi.py +76 -63
  42. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_given.py +4 -3
  43. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_inject.py +7 -7
  44. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_injected.py +3 -2
  45. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_overrides.py +14 -6
  46. fastapi_injected-0.4.0/tests/test_reflect.py +484 -0
  47. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_request_params.py +12 -9
  48. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_resolve.py +4 -4
  49. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/uv.lock +196 -196
  50. fastapi_injected-0.3.6/fastapi_injected/__init__.py +0 -60
  51. fastapi_injected-0.3.6/fastapi_injected/overrides.py +0 -36
  52. fastapi_injected-0.3.6/fastapi_injected/sign.py +0 -92
  53. fastapi_injected-0.3.6/tests/_typing/integration.py +0 -38
  54. fastapi_injected-0.3.6/tests/_typing/scope.py +0 -67
  55. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/.github/dependabot.yml +0 -0
  56. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/.github/workflows/automerge.yml +0 -0
  57. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/.github/workflows/lint.yml +0 -0
  58. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/.github/workflows/publish.yml +0 -0
  59. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/.github/workflows/test.yml +0 -0
  60. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/.gitignore +0 -0
  61. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/.pre-commit-config.yaml +0 -0
  62. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/LICENSE +0 -0
  63. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_body.py +0 -0
  64. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_dataclass.py +0 -0
  65. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_given.py +0 -0
  66. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_injected.py +0 -0
  67. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/fastapi_injected/_rlock.py +0 -0
  68. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/__init__.py +0 -0
  69. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/__init__.py +0 -0
  70. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/arg.py +0 -0
  71. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/deps.py +0 -0
  72. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/errors.py +0 -0
  73. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/given.py +0 -0
  74. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/_typing/markers.py +0 -0
  75. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/deps.py +0 -0
  76. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/ext/__init__.py +0 -0
  77. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/ext/test_pydantic_ai.py +0 -0
  78. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_errors.py +0 -0
  79. {fastapi_injected-0.3.6 → fastapi_injected-0.4.0}/tests/test_rlock.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: fastapi-injected
3
- Version: 0.3.6
3
+ Version: 0.4.0
4
4
  Summary: Yet another library to reuse fastapi dependency injection
5
5
  Project-URL: Repository, https://github.com/uriyyo/fastapi-injected
6
6
  Author-email: Yurii Karabas <1998uriyyo@gmail.com>
@@ -138,47 +138,47 @@ from fastapi_injected import resolve
138
138
  service = await resolve(Service)
139
139
  ```
140
140
 
141
- Like `@inject`, `resolve` accepts `new_scope=True` to force a fresh scope instead of reusing the surrounding one.
141
+ Like `@inject`, `resolve` accepts `new_ctx=True` to force a fresh context instead of reusing the surrounding one.
142
142
 
143
- ### Scopes and caching
143
+ ### Contexts and caching
144
144
 
145
- By default every call to an injected function gets its own scope: dependencies are built, cached within the call, and torn down when it returns. Wrap several calls in `push_inject_scope()` to share one cache (and defer teardown to the end of the scope):
145
+ By default every call to an injected function gets its own injection context: dependencies are built, cached within the call, and torn down when it returns. Wrap several calls in `injection_ctx()` to share one cache (and defer teardown to the end of the context):
146
146
 
147
147
  ```python
148
- from fastapi_injected import push_inject_scope
148
+ from fastapi_injected import injection_ctx
149
149
 
150
- async with push_inject_scope():
150
+ async with injection_ctx():
151
151
  a = await handler() # dependencies built here
152
152
  b = await handler() # same instances reused
153
153
  # generator dependencies are torn down here
154
154
  ```
155
155
 
156
- Use `@inject(new_scope=True)` to opt a function out of the surrounding scope and always get fresh dependencies. It builds them again, but stays in the request they are being built for, so request-bound dependencies keep resolving.
156
+ Use `@inject(new_ctx=True)` to opt a function out of the surrounding context and always get fresh dependencies. It builds them again, but stays in the request they are being built for, so request-bound dependencies keep resolving.
157
157
 
158
- Outside of a request there is no request to resolve against, so the scope makes one up. It answers what a dependency usually reads — `method`, `url`, `headers`, `path_params`, `client`, `state` — with the values of a request nobody sent. The application is the one thing it cannot invent: pass it when a dependency reaches for `request.app`:
158
+ Outside of a request there is no request to resolve against, so the context makes one up. It answers what a dependency usually reads — `method`, `url`, `headers`, `path_params`, `client`, `state` — with the values of a request nobody sent. The application is the one thing it cannot invent: pass it when a dependency reaches for `request.app`:
159
159
 
160
160
  ```python
161
- async with push_inject_scope(app=app):
161
+ async with injection_ctx(app=app):
162
162
  await handler() # `request.app.state` resolves as it does in a route
163
163
  ```
164
164
 
165
165
  Without it, reading `request.app` raises a `KeyError` naming what is missing rather than a bare `'app'`.
166
166
 
167
- When a dependency reads more of the request than that — a header, a cookie, a query or path parameter, the body — describe the request with `synthetic_request` and hand it to the scope:
167
+ When a dependency reads more of the request than that — a header, a cookie, a query or path parameter, the body — describe the request with `synthetic_request` and hand it to the context:
168
168
 
169
169
  ```python
170
- from fastapi_injected import push_inject_scope, synthetic_request
170
+ from fastapi_injected import injection_ctx, synthetic_request
171
171
 
172
172
  request = synthetic_request(
173
173
  headers={"x-trace": "job-42"},
174
174
  cookies={"sid": "abc"},
175
- query={"page": "2"},
175
+ query_params={"page": "2"},
176
176
  path_params={"item_id": 7},
177
177
  body={"name": "readme"}, # sent as JSON; bytes and str are sent as they are
178
178
  app=app,
179
179
  )
180
180
 
181
- async with push_inject_scope(request=request):
181
+ async with injection_ctx(request=request):
182
182
  await handler() # `Header()`, `Cookie()`, `Query()`, `Path()` and `Body()` resolve from it
183
183
  ```
184
184
 
@@ -202,9 +202,9 @@ with push_overrides({DepFactory[Session, session_dep]: my_session}):
202
202
  ...
203
203
  ```
204
204
 
205
- Values are used as-is, but two wrappers make the intent explicit and cover the ambiguous cases:
205
+ A callable value is called to produce the dependency, as in FastAPI's `dependency_overrides`; anything else is injected as it is. Two wrappers make the intent explicit and cover the ambiguous cases:
206
206
 
207
- - `ValueOverride(value)` — always inject `value`, even when it is itself callable.
207
+ - `ValueOverride(value)` — always inject `value`, even when it is itself callable (a class, a mock, a function object).
208
208
  - `FactoryOverride(factory)` — call `factory` to produce the value. Sync, async, and generator factories are all supported, with the same teardown semantics as regular dependencies.
209
209
 
210
210
  ```python
@@ -221,10 +221,10 @@ with push_overrides(
221
221
 
222
222
  Overrides apply to the whole graph, not just top-level parameters — overriding a nested dependency changes what its dependents receive. Nested `push_overrides` blocks merge, with the innermost one winning.
223
223
 
224
- An override block is a scope of its own: it caches what it builds, and that cache goes away with the block. The surrounding scope keeps what it had resolved before, and it stays visible — except for the overridden dependencies and anything built from them, which are resolved again under the override:
224
+ An override block is a context of its own: it caches what it builds, and that cache goes away with the block. The surrounding context keeps what it had resolved before, and it stays visible — except for the overridden dependencies and anything built from them, which are resolved again under the override:
225
225
 
226
226
  ```python
227
- async with push_inject_scope():
227
+ async with injection_ctx():
228
228
  real = await handler() # dependencies cached here
229
229
 
230
230
  with push_overrides({Session: fake}):
@@ -233,25 +233,28 @@ async with push_inject_scope():
233
233
  await handler() # back to the cached, real dependencies
234
234
  ```
235
235
 
236
- Overrides can also be handed to the scope directly, which is the same thing in one call:
236
+ Overrides can also be handed to the context directly, which is the same thing in one call:
237
237
 
238
238
  ```python
239
- async with push_inject_scope({Session: fake}) as scope:
239
+ async with injection_ctx({Session: fake}) as ctx:
240
240
  await handler()
241
241
 
242
- with scope.override({Session: other}): # nest freely
242
+ with ctx.override({Session: other}): # nest freely
243
243
  await handler()
244
244
  ```
245
245
 
246
+ For FastAPI's own `app.dependency_overrides`, `override_app(app, {dep: fake})` sets entries for a `with` block and restores the previous mapping afterwards, including entries added inside the block.
247
+
246
248
  ### Dependencies that are objects
247
249
 
248
- Resolved values are cached in their scope by the callable that resolves them, so a dependency that is an object — a class holding configuration, a parametrized resolver — has to be hashable to get there. A plain dataclass is not, and a frozen one still refuses as soon as it holds a list or a dict.
250
+ Resolved values are cached in their context by the callable that resolves them, so a dependency that is an object — a class holding configuration, a parametrized resolver — has to be hashable to get there. A plain dataclass is not, and a frozen one still refuses as soon as it holds a list or a dict.
249
251
 
250
252
  `MakeDataclass` is a base class that makes its subclasses dataclasses with a hash that always answers: by fields when they can be hashed, by identity when they cannot.
251
253
 
252
254
  ```python
253
255
  from dataclasses import field
254
- from fastapi_injected import MakeDataclass, resolve
256
+ from fastapi_injected import resolve
257
+ from fastapi_injected.ext import MakeDataclass
255
258
 
256
259
 
257
260
  class Settings(MakeDataclass):
@@ -324,7 +327,8 @@ Binding takes the parameters away, and a type checker sees what is left: `bind_d
324
327
  When the markers belong together, `MakeInjected` makes a dataclass of them: fields annotated with `DepOf` hold the markers, and the call receives what they resolve to.
325
328
 
326
329
  ```python
327
- from fastapi_injected import Given, MakeInjected
330
+ from fastapi_injected import Given
331
+ from fastapi_injected.ext import MakeInjected
328
332
  from fastapi_injected.types import DepOf
329
333
 
330
334
 
@@ -340,25 +344,67 @@ class IsOwner(MakeInjected):
340
344
  await resolve(IsOwner(doc=Given(doc), role=RoleDep))
341
345
  ```
342
346
 
343
- It is a `MakeDataclass`, so instances built from equal markers are equal — and therefore one dependency, resolved once per scope and overridable as a whole. For callables that are not dataclasses, the two halves of the binding are available on their own: `signature_with_deps(func, deps)` builds the signature, and `remap_dep_args` turns the arguments it names back into positional ones.
347
+ It is a `MakeDataclass`, so instances built from equal markers are equal — and therefore one dependency, resolved once per context and overridable as a whole. For callables that are not dataclasses, the two halves of the binding are available on their own: `signature_with_deps(func, deps)` builds the signature, and `remap_dep_args` turns the arguments it names back into positional ones.
344
348
 
345
349
  ### Inspecting annotations
346
350
 
347
- A few helpers are exported for code that needs to reason about `Dep[...]` annotations — building override maps, custom decorators, and the like:
351
+ `fastapi_injected.ext` holds a few helpers for code that needs to reason about `Dep[...]` annotations — building override maps, custom decorators, and the like:
348
352
 
349
353
  - `is_dep(tp)` — whether `tp` is a `Dep`/`DepFactory` annotation.
350
354
  - `unwrap_dep_tp(tp)` — the annotated type (`Any` for a bare `Dep`).
351
355
  - `unwrap_dep_dependency(tp)` — the callable that resolves it: the factory for `DepFactory[T, factory]`, the type itself for `Dep[T]`.
352
356
 
357
+ ### Reflecting on apps and dependency trees
358
+
359
+ `fastapi_injected.reflect` answers the questions tests and tooling keep asking about an app, without walking `Dependant` trees or `app.routes` by hand.
360
+
361
+ ```python
362
+ from fastapi_injected.reflect import find_route, iter_api_routes, iter_calls, iter_security
363
+
364
+ # every APIRoute with its full path, through include_router, Mount and Host
365
+ for path, route in iter_api_routes(app):
366
+ assert get_current_user in iter_calls(route.dependant), path
367
+
368
+ route = find_route(app, method="POST", path="/items") # or name="create_item"
369
+
370
+ # security schemes a route (or any callable) pulls in, with their OAuth scopes
371
+ assert list(iter_security(route.dependant)) == [(bearer, ["items:write"])]
372
+ ```
373
+
374
+ - `iter_dependant(root, *, mode="bfs" | "dfs")` — every `Dependant` under `root`, the root first.
375
+ - `iter_calls(root, *, expand=None)` — unique callables `root` depends on, the root itself excluded. `expand(call)` returns extra calls to report for callables that hold more dependencies than their signature shows, such as composite permissions.
376
+ - `iter_security(root)` — `(scheme, scopes)` for every `SecurityBase` in the tree.
377
+ - `find_dependant(root, call)` — the chain of dependants from the root down to `call`, for saying *through what* a dependency is reached.
378
+ - `iter_overridden(root, overrides)` — the calls an override map or collection replaces, including every dependant above a replaced one, which is what stops caching across an override.
379
+ - `iter_routes(app)` — `(path, route)` for every route, with mounts, hosts and included routers expanded and the path prefixed accordingly. `iter_api_routes` keeps only FastAPI's HTTP and websocket routes, and `find_route(app, *, method=, path=, name=)` returns the first one matching every given filter, raising `LookupError` otherwise. Websocket routes answer to the method `WEBSOCKET`.
380
+ - `iter_routes_where(app, pred)` — `(method, path, route)` for every route `pred` accepts, one entry per method. The usual authorization test is `iter_routes_where(app, lambda r: guard not in iter_calls(r.dependant))`.
381
+ - `iter_operations(app_or_schema)` and `operation_for(app_or_schema, method, path)` — walk the OpenAPI document by `(path, method, operation)` instead of indexing nested dicts.
382
+ - `iter_routers(app)` — `(prefix, router)` for the app's router and every router included or mounted under it.
383
+ - `match_route(app, request_or_scope)` — `(path_template, route)` for the route that would handle a request, through mounts, hosts and included routers; `None` when nothing matches. Useful in middleware, where `request.scope["route"]` is not set yet.
384
+ - `iter_params(root)` — `(dependant, kind, field)` for every path, query, header, cookie and body parameter in the tree.
385
+ - `response_type(route, *, strip=True)` — the route's response type, falling back to the endpoint's return annotation, with `Annotated` and `| None` stripped unless `strip=False`.
386
+ - `Signature`, in `fastapi_injected.signature`, is an `inspect.Signature` with operations for decorators and dependencies that need FastAPI to see parameters a function did not declare. `Signature.of(func_or_signature)` starts one; each operation returns a new `Signature`, and `.apply(func)` sets it on a function.
387
+ - `.add(*parameters)` — extra keyword-only parameters before `**kwargs`; names already present are kept as they are.
388
+ - `.drop(*names)` and `.update(name, **changes)` — drop parameters a wrapper consumes itself, or change one parameter's annotation, default or kind.
389
+ - `.add_dep(name, dep, *, annotation=Any)` — a parameter FastAPI resolves with a `Depends`/`Security` marker or a callable.
390
+ - `.prepend(*parameters)`, `.rename(old, new)` and `.returns(annotation)` — positional parameters at the front, a renamed parameter, a new return annotation.
391
+ - `Signature.role(parameter)` — which `ParamRole` a parameter plays: `dep` for `Dep[...]` or a `Depends` default, `request` for `Header()`/`Query()`/..., `arg` for `Arg[...]`, `plain` otherwise. `.select(*roles)` yields the parameters with those roles; `.annotations` and `.defaults` are name-to-value mappings of what is declared.
392
+ - `.wrap(func)` — a forwarder to `func`, async when `func` is, carrying this signature; `.apply(func)` sets the signature on `func` itself.
393
+ - `add_route_dependency(route, *deps)` — append dependencies to an `APIRoute` that is already built, and rebuild what FastAPI derived from its dependencies. Call it before the route's router is included elsewhere: an included router keeps its own copy until its routes change.
394
+ - `add_lifespan(app_or_router, lifespan)` — run a lifespan inside the one already set, merging the state both yield, for libraries that need a startup step on an app they did not create.
395
+
396
+ `root` for the dependency helpers is a `Dependant`, a `Depends(...)` marker or a plain callable; `as_dependant` is the conversion they share. A plain callable is read the way FastAPI would, with `Injected` defaults treated as dependencies.
397
+
353
398
  ### FastAPI request integration
354
399
 
355
- Inside a FastAPI app, `@inject`-ed functions and `resolve` can share the request's own dependency cache — the same instances FastAPI built for the handler. Register `init_inject_scope` as a dependency:
400
+ Inside a FastAPI app, `@inject`-ed functions and `resolve` can share the request's own dependency cache — the same instances FastAPI built for the handler. Call `add_injection`: it adds `InjectionMiddleware`, which opens the context for the whole request, and the `bind_injection_ctx` dependency, which binds it to the connection of the route. Add it after your other middleware, so the context is open for them too:
356
401
 
357
402
  ```python
358
- from fastapi import Depends, FastAPI
359
- from fastapi_injected import Dep, init_inject_scope, resolve
403
+ from fastapi import FastAPI
404
+ from fastapi_injected import Dep, add_injection, resolve
360
405
 
361
- app = FastAPI(dependencies=[Depends(init_inject_scope)])
406
+ app = FastAPI()
407
+ add_injection(app)
362
408
 
363
409
 
364
410
  @app.get("/")
@@ -367,9 +413,9 @@ async def route(service: Dep[Service]) -> str:
367
413
  ...
368
414
  ```
369
415
 
370
- Anything called from the handler — including `@inject`-ed helpers — resolves against the request's cache, so a per-request dependency like a DB session stays a single instance for the whole request.
416
+ Anything called from the handler — including `@inject`-ed helpers — resolves against the request's cache, so a per-request dependency like a DB session stays a single instance for the whole request. The context is opened by a middleware, so `resolve` also works inside middleware added before it (before routing, `request.scope["route"]` and path params are not available yet).
371
417
 
372
- WebSocket routes work the same way: the scope is bound to the `WebSocket` instead of a `Request`, and dependencies that ask for one get it. A websocket handed to a dependency shares its handshake with the one the route received, so it can be talked through after the route has called `accept()`:
418
+ WebSocket routes work the same way: the context is bound to the `WebSocket` instead of a `Request`, and dependencies that ask for one get it. A websocket handed to a dependency shares its handshake with the one the route received, so it can be talked through after the route has called `accept()`:
373
419
 
374
420
  ```python
375
421
  async def notify(websocket: WebSocket) -> None:
@@ -382,7 +428,7 @@ async def ws_route(websocket: WebSocket, service: Dep[Service]) -> None:
382
428
  await resolve(notify) # sends through the connection the route accepted
383
429
  ```
384
430
 
385
- Dependencies that take request parameters — `Header()`, `Cookie()`, `Query()`, `Path()`, and the body as `Body()`, `Form()`, `File()` or a pydantic model — resolve from the request the scope is bound to, exactly as they would in the route:
431
+ Dependencies that take request parameters — `Header()`, `Cookie()`, `Query()`, `Path()`, and the body as `Body()`, `Form()`, `File()` or a pydantic model — resolve from the request the context is bound to, exactly as they would in the route:
386
432
 
387
433
  ```python
388
434
  class Item(BaseModel):
@@ -413,24 +459,34 @@ async def handler(*, api_key: Annotated[str, Header()] = Injected) -> str:
413
459
  return api_key # a parameter has a name - `x-api-key`, as FastAPI derives it
414
460
  ```
415
461
 
416
- The body is read only when the resolved dependency declares one, and it is read once per request, shared with the route and every scope nested in it. When the route itself declares a body, dependencies see it in the shape the route gave it: a route with several body parameters embeds them under their names, and a dependency reads its own from there.
462
+ The body is read only when the resolved dependency declares one, and it is read once per request, shared with the route and every context nested in it. When the route itself declares a body, dependencies see it in the shape the route gave it: a route with several body parameters embeds them under their names, and a dependency reads its own from there.
417
463
 
418
- `push_inject_scope(request=...)` accepts either a `Request` or a `WebSocket`, and so does everything that reads `InjectScope.request` — the union is `fastapi_injected.types.BoundConnection`.
464
+ `injection_ctx(request=...)` accepts either a `Request` or a `WebSocket`, and so does everything that reads `InjectionContext.request` — the union is `fastapi_injected.types.BoundConnection`.
419
465
 
420
466
  ## What is public
421
467
 
422
- Everything the package supports is importable from `fastapi_injected` itself, and that is the surface a release keeps:
468
+ The root package is what you need to use the library, and the surface a release keeps:
423
469
 
424
470
  | | |
425
471
  | --- | --- |
426
- | Markers | `Dep`, `DepFactory`, `DepOf`, `Arg`, `Given`, `Injected` |
427
- | Resolving | `inject`, `resolve`, `bind_deps`, `signature_with_deps`, `remap_dep_args`, `clear_dependant_cache` |
428
- | Scopes and overrides | `InjectScope`, `push_inject_scope`, `inside_inject_scope`, `synthetic_request`, `push_overrides`, `Overrides`, `OverridesProvider`, `ValueOverride`, `FactoryOverride` |
429
- | Building on top | `MakeDataclass`, `MakeInjected`, `HasDependsHook`, `ArgMarker`, `is_arg`, `is_dep`, `unwrap_dep_tp`, `unwrap_dep_dependency` |
430
- | FastAPI integration | `add_injected_scope`, `init_inject_scope` |
431
- | Errors | `DependencyResolutionError`, `MissedDependencyError`, `MissingDependencyCacheError`, `NotADependencyError`, `UnboundDepArgsError`, `UnboundScopeError`, `UnnamedParamError` |
432
-
433
- `fastapi_injected.types` holds the typing vocabulary the signatures are written in — `DepReturn`, `DepShape`, `DepDecl`, `AsyncFunc`, `Coro` and friends — and is public too. Anything else, including every module whose name starts with an underscore, is machinery that can change in a patch release.
472
+ | Markers | `Dep`, `DepFactory`, `Arg`, `Given`, `Injected` |
473
+ | Resolving | `inject`, `resolve`, `bind_deps` |
474
+ | Contexts and overrides | `InjectionContext`, `injection_ctx`, `synthetic_request`, `push_overrides`, `override_app`, `ValueOverride`, `FactoryOverride` |
475
+ | FastAPI integration | `add_injection` |
476
+ | Errors | `DependencyResolutionError`, `NotADependencyError`, `UnboundContextError`, `UnnamedParamError` |
477
+
478
+ Code that builds on the library imports from the submodule that owns the piece. These are public too:
479
+
480
+ | Module | Names |
481
+ | --- | --- |
482
+ | `fastapi_injected.ext` | `MakeDataclass`, `MakeInjected`, `signature_with_deps`, `remap_dep_args`, `is_dep`, `is_arg`, `unwrap_dep_tp`, `unwrap_dep_dependency`, `strip_annotation`, `as_depends`, `clear_dependant_cache`, `ensure_injection_ctx`, `MissedDependencyError`, `UnboundDepArgsError` |
483
+ | `fastapi_injected.types` | `DepOf`, `ArgMarker`, `HasDependsHook`, and the typing vocabulary the signatures are written in — `DepReturn`, `DepShape`, `DepDecl`, `AsyncFunc`, `Coro`, `BoundConnection`, `DependencyCache` and friends |
484
+ | `fastapi_injected.overrides` | `Overrides`, `OverridesProvider` |
485
+ | `fastapi_injected.signature` | `Signature`, `ParamRole` |
486
+ | `fastapi_injected.fastapi` | `InjectionMiddleware`, `bind_injection_ctx`, `MissingDependencyCacheError` |
487
+ | `fastapi_injected.reflect` | `iter_dependant`, `iter_calls`, `iter_security`, `iter_params`, `find_dependant`, `iter_overridden`, `iter_routes`, `iter_api_routes`, `iter_routes_where`, `find_route`, `match_route`, `iter_routers`, `response_type`, `add_route_dependency`, `add_lifespan`, `iter_operations`, `operation_for`, `as_dependant` |
488
+
489
+ Anything else, including every module whose name starts with an underscore, is machinery that can change in a patch release.
434
490
 
435
491
  ## License
436
492
 
@@ -117,47 +117,47 @@ from fastapi_injected import resolve
117
117
  service = await resolve(Service)
118
118
  ```
119
119
 
120
- Like `@inject`, `resolve` accepts `new_scope=True` to force a fresh scope instead of reusing the surrounding one.
120
+ Like `@inject`, `resolve` accepts `new_ctx=True` to force a fresh context instead of reusing the surrounding one.
121
121
 
122
- ### Scopes and caching
122
+ ### Contexts and caching
123
123
 
124
- By default every call to an injected function gets its own scope: dependencies are built, cached within the call, and torn down when it returns. Wrap several calls in `push_inject_scope()` to share one cache (and defer teardown to the end of the scope):
124
+ By default every call to an injected function gets its own injection context: dependencies are built, cached within the call, and torn down when it returns. Wrap several calls in `injection_ctx()` to share one cache (and defer teardown to the end of the context):
125
125
 
126
126
  ```python
127
- from fastapi_injected import push_inject_scope
127
+ from fastapi_injected import injection_ctx
128
128
 
129
- async with push_inject_scope():
129
+ async with injection_ctx():
130
130
  a = await handler() # dependencies built here
131
131
  b = await handler() # same instances reused
132
132
  # generator dependencies are torn down here
133
133
  ```
134
134
 
135
- Use `@inject(new_scope=True)` to opt a function out of the surrounding scope and always get fresh dependencies. It builds them again, but stays in the request they are being built for, so request-bound dependencies keep resolving.
135
+ Use `@inject(new_ctx=True)` to opt a function out of the surrounding context and always get fresh dependencies. It builds them again, but stays in the request they are being built for, so request-bound dependencies keep resolving.
136
136
 
137
- Outside of a request there is no request to resolve against, so the scope makes one up. It answers what a dependency usually reads — `method`, `url`, `headers`, `path_params`, `client`, `state` — with the values of a request nobody sent. The application is the one thing it cannot invent: pass it when a dependency reaches for `request.app`:
137
+ Outside of a request there is no request to resolve against, so the context makes one up. It answers what a dependency usually reads — `method`, `url`, `headers`, `path_params`, `client`, `state` — with the values of a request nobody sent. The application is the one thing it cannot invent: pass it when a dependency reaches for `request.app`:
138
138
 
139
139
  ```python
140
- async with push_inject_scope(app=app):
140
+ async with injection_ctx(app=app):
141
141
  await handler() # `request.app.state` resolves as it does in a route
142
142
  ```
143
143
 
144
144
  Without it, reading `request.app` raises a `KeyError` naming what is missing rather than a bare `'app'`.
145
145
 
146
- When a dependency reads more of the request than that — a header, a cookie, a query or path parameter, the body — describe the request with `synthetic_request` and hand it to the scope:
146
+ When a dependency reads more of the request than that — a header, a cookie, a query or path parameter, the body — describe the request with `synthetic_request` and hand it to the context:
147
147
 
148
148
  ```python
149
- from fastapi_injected import push_inject_scope, synthetic_request
149
+ from fastapi_injected import injection_ctx, synthetic_request
150
150
 
151
151
  request = synthetic_request(
152
152
  headers={"x-trace": "job-42"},
153
153
  cookies={"sid": "abc"},
154
- query={"page": "2"},
154
+ query_params={"page": "2"},
155
155
  path_params={"item_id": 7},
156
156
  body={"name": "readme"}, # sent as JSON; bytes and str are sent as they are
157
157
  app=app,
158
158
  )
159
159
 
160
- async with push_inject_scope(request=request):
160
+ async with injection_ctx(request=request):
161
161
  await handler() # `Header()`, `Cookie()`, `Query()`, `Path()` and `Body()` resolve from it
162
162
  ```
163
163
 
@@ -181,9 +181,9 @@ with push_overrides({DepFactory[Session, session_dep]: my_session}):
181
181
  ...
182
182
  ```
183
183
 
184
- Values are used as-is, but two wrappers make the intent explicit and cover the ambiguous cases:
184
+ A callable value is called to produce the dependency, as in FastAPI's `dependency_overrides`; anything else is injected as it is. Two wrappers make the intent explicit and cover the ambiguous cases:
185
185
 
186
- - `ValueOverride(value)` — always inject `value`, even when it is itself callable.
186
+ - `ValueOverride(value)` — always inject `value`, even when it is itself callable (a class, a mock, a function object).
187
187
  - `FactoryOverride(factory)` — call `factory` to produce the value. Sync, async, and generator factories are all supported, with the same teardown semantics as regular dependencies.
188
188
 
189
189
  ```python
@@ -200,10 +200,10 @@ with push_overrides(
200
200
 
201
201
  Overrides apply to the whole graph, not just top-level parameters — overriding a nested dependency changes what its dependents receive. Nested `push_overrides` blocks merge, with the innermost one winning.
202
202
 
203
- An override block is a scope of its own: it caches what it builds, and that cache goes away with the block. The surrounding scope keeps what it had resolved before, and it stays visible — except for the overridden dependencies and anything built from them, which are resolved again under the override:
203
+ An override block is a context of its own: it caches what it builds, and that cache goes away with the block. The surrounding context keeps what it had resolved before, and it stays visible — except for the overridden dependencies and anything built from them, which are resolved again under the override:
204
204
 
205
205
  ```python
206
- async with push_inject_scope():
206
+ async with injection_ctx():
207
207
  real = await handler() # dependencies cached here
208
208
 
209
209
  with push_overrides({Session: fake}):
@@ -212,25 +212,28 @@ async with push_inject_scope():
212
212
  await handler() # back to the cached, real dependencies
213
213
  ```
214
214
 
215
- Overrides can also be handed to the scope directly, which is the same thing in one call:
215
+ Overrides can also be handed to the context directly, which is the same thing in one call:
216
216
 
217
217
  ```python
218
- async with push_inject_scope({Session: fake}) as scope:
218
+ async with injection_ctx({Session: fake}) as ctx:
219
219
  await handler()
220
220
 
221
- with scope.override({Session: other}): # nest freely
221
+ with ctx.override({Session: other}): # nest freely
222
222
  await handler()
223
223
  ```
224
224
 
225
+ For FastAPI's own `app.dependency_overrides`, `override_app(app, {dep: fake})` sets entries for a `with` block and restores the previous mapping afterwards, including entries added inside the block.
226
+
225
227
  ### Dependencies that are objects
226
228
 
227
- Resolved values are cached in their scope by the callable that resolves them, so a dependency that is an object — a class holding configuration, a parametrized resolver — has to be hashable to get there. A plain dataclass is not, and a frozen one still refuses as soon as it holds a list or a dict.
229
+ Resolved values are cached in their context by the callable that resolves them, so a dependency that is an object — a class holding configuration, a parametrized resolver — has to be hashable to get there. A plain dataclass is not, and a frozen one still refuses as soon as it holds a list or a dict.
228
230
 
229
231
  `MakeDataclass` is a base class that makes its subclasses dataclasses with a hash that always answers: by fields when they can be hashed, by identity when they cannot.
230
232
 
231
233
  ```python
232
234
  from dataclasses import field
233
- from fastapi_injected import MakeDataclass, resolve
235
+ from fastapi_injected import resolve
236
+ from fastapi_injected.ext import MakeDataclass
234
237
 
235
238
 
236
239
  class Settings(MakeDataclass):
@@ -303,7 +306,8 @@ Binding takes the parameters away, and a type checker sees what is left: `bind_d
303
306
  When the markers belong together, `MakeInjected` makes a dataclass of them: fields annotated with `DepOf` hold the markers, and the call receives what they resolve to.
304
307
 
305
308
  ```python
306
- from fastapi_injected import Given, MakeInjected
309
+ from fastapi_injected import Given
310
+ from fastapi_injected.ext import MakeInjected
307
311
  from fastapi_injected.types import DepOf
308
312
 
309
313
 
@@ -319,25 +323,67 @@ class IsOwner(MakeInjected):
319
323
  await resolve(IsOwner(doc=Given(doc), role=RoleDep))
320
324
  ```
321
325
 
322
- It is a `MakeDataclass`, so instances built from equal markers are equal — and therefore one dependency, resolved once per scope and overridable as a whole. For callables that are not dataclasses, the two halves of the binding are available on their own: `signature_with_deps(func, deps)` builds the signature, and `remap_dep_args` turns the arguments it names back into positional ones.
326
+ It is a `MakeDataclass`, so instances built from equal markers are equal — and therefore one dependency, resolved once per context and overridable as a whole. For callables that are not dataclasses, the two halves of the binding are available on their own: `signature_with_deps(func, deps)` builds the signature, and `remap_dep_args` turns the arguments it names back into positional ones.
323
327
 
324
328
  ### Inspecting annotations
325
329
 
326
- A few helpers are exported for code that needs to reason about `Dep[...]` annotations — building override maps, custom decorators, and the like:
330
+ `fastapi_injected.ext` holds a few helpers for code that needs to reason about `Dep[...]` annotations — building override maps, custom decorators, and the like:
327
331
 
328
332
  - `is_dep(tp)` — whether `tp` is a `Dep`/`DepFactory` annotation.
329
333
  - `unwrap_dep_tp(tp)` — the annotated type (`Any` for a bare `Dep`).
330
334
  - `unwrap_dep_dependency(tp)` — the callable that resolves it: the factory for `DepFactory[T, factory]`, the type itself for `Dep[T]`.
331
335
 
336
+ ### Reflecting on apps and dependency trees
337
+
338
+ `fastapi_injected.reflect` answers the questions tests and tooling keep asking about an app, without walking `Dependant` trees or `app.routes` by hand.
339
+
340
+ ```python
341
+ from fastapi_injected.reflect import find_route, iter_api_routes, iter_calls, iter_security
342
+
343
+ # every APIRoute with its full path, through include_router, Mount and Host
344
+ for path, route in iter_api_routes(app):
345
+ assert get_current_user in iter_calls(route.dependant), path
346
+
347
+ route = find_route(app, method="POST", path="/items") # or name="create_item"
348
+
349
+ # security schemes a route (or any callable) pulls in, with their OAuth scopes
350
+ assert list(iter_security(route.dependant)) == [(bearer, ["items:write"])]
351
+ ```
352
+
353
+ - `iter_dependant(root, *, mode="bfs" | "dfs")` — every `Dependant` under `root`, the root first.
354
+ - `iter_calls(root, *, expand=None)` — unique callables `root` depends on, the root itself excluded. `expand(call)` returns extra calls to report for callables that hold more dependencies than their signature shows, such as composite permissions.
355
+ - `iter_security(root)` — `(scheme, scopes)` for every `SecurityBase` in the tree.
356
+ - `find_dependant(root, call)` — the chain of dependants from the root down to `call`, for saying *through what* a dependency is reached.
357
+ - `iter_overridden(root, overrides)` — the calls an override map or collection replaces, including every dependant above a replaced one, which is what stops caching across an override.
358
+ - `iter_routes(app)` — `(path, route)` for every route, with mounts, hosts and included routers expanded and the path prefixed accordingly. `iter_api_routes` keeps only FastAPI's HTTP and websocket routes, and `find_route(app, *, method=, path=, name=)` returns the first one matching every given filter, raising `LookupError` otherwise. Websocket routes answer to the method `WEBSOCKET`.
359
+ - `iter_routes_where(app, pred)` — `(method, path, route)` for every route `pred` accepts, one entry per method. The usual authorization test is `iter_routes_where(app, lambda r: guard not in iter_calls(r.dependant))`.
360
+ - `iter_operations(app_or_schema)` and `operation_for(app_or_schema, method, path)` — walk the OpenAPI document by `(path, method, operation)` instead of indexing nested dicts.
361
+ - `iter_routers(app)` — `(prefix, router)` for the app's router and every router included or mounted under it.
362
+ - `match_route(app, request_or_scope)` — `(path_template, route)` for the route that would handle a request, through mounts, hosts and included routers; `None` when nothing matches. Useful in middleware, where `request.scope["route"]` is not set yet.
363
+ - `iter_params(root)` — `(dependant, kind, field)` for every path, query, header, cookie and body parameter in the tree.
364
+ - `response_type(route, *, strip=True)` — the route's response type, falling back to the endpoint's return annotation, with `Annotated` and `| None` stripped unless `strip=False`.
365
+ - `Signature`, in `fastapi_injected.signature`, is an `inspect.Signature` with operations for decorators and dependencies that need FastAPI to see parameters a function did not declare. `Signature.of(func_or_signature)` starts one; each operation returns a new `Signature`, and `.apply(func)` sets it on a function.
366
+ - `.add(*parameters)` — extra keyword-only parameters before `**kwargs`; names already present are kept as they are.
367
+ - `.drop(*names)` and `.update(name, **changes)` — drop parameters a wrapper consumes itself, or change one parameter's annotation, default or kind.
368
+ - `.add_dep(name, dep, *, annotation=Any)` — a parameter FastAPI resolves with a `Depends`/`Security` marker or a callable.
369
+ - `.prepend(*parameters)`, `.rename(old, new)` and `.returns(annotation)` — positional parameters at the front, a renamed parameter, a new return annotation.
370
+ - `Signature.role(parameter)` — which `ParamRole` a parameter plays: `dep` for `Dep[...]` or a `Depends` default, `request` for `Header()`/`Query()`/..., `arg` for `Arg[...]`, `plain` otherwise. `.select(*roles)` yields the parameters with those roles; `.annotations` and `.defaults` are name-to-value mappings of what is declared.
371
+ - `.wrap(func)` — a forwarder to `func`, async when `func` is, carrying this signature; `.apply(func)` sets the signature on `func` itself.
372
+ - `add_route_dependency(route, *deps)` — append dependencies to an `APIRoute` that is already built, and rebuild what FastAPI derived from its dependencies. Call it before the route's router is included elsewhere: an included router keeps its own copy until its routes change.
373
+ - `add_lifespan(app_or_router, lifespan)` — run a lifespan inside the one already set, merging the state both yield, for libraries that need a startup step on an app they did not create.
374
+
375
+ `root` for the dependency helpers is a `Dependant`, a `Depends(...)` marker or a plain callable; `as_dependant` is the conversion they share. A plain callable is read the way FastAPI would, with `Injected` defaults treated as dependencies.
376
+
332
377
  ### FastAPI request integration
333
378
 
334
- Inside a FastAPI app, `@inject`-ed functions and `resolve` can share the request's own dependency cache — the same instances FastAPI built for the handler. Register `init_inject_scope` as a dependency:
379
+ Inside a FastAPI app, `@inject`-ed functions and `resolve` can share the request's own dependency cache — the same instances FastAPI built for the handler. Call `add_injection`: it adds `InjectionMiddleware`, which opens the context for the whole request, and the `bind_injection_ctx` dependency, which binds it to the connection of the route. Add it after your other middleware, so the context is open for them too:
335
380
 
336
381
  ```python
337
- from fastapi import Depends, FastAPI
338
- from fastapi_injected import Dep, init_inject_scope, resolve
382
+ from fastapi import FastAPI
383
+ from fastapi_injected import Dep, add_injection, resolve
339
384
 
340
- app = FastAPI(dependencies=[Depends(init_inject_scope)])
385
+ app = FastAPI()
386
+ add_injection(app)
341
387
 
342
388
 
343
389
  @app.get("/")
@@ -346,9 +392,9 @@ async def route(service: Dep[Service]) -> str:
346
392
  ...
347
393
  ```
348
394
 
349
- Anything called from the handler — including `@inject`-ed helpers — resolves against the request's cache, so a per-request dependency like a DB session stays a single instance for the whole request.
395
+ Anything called from the handler — including `@inject`-ed helpers — resolves against the request's cache, so a per-request dependency like a DB session stays a single instance for the whole request. The context is opened by a middleware, so `resolve` also works inside middleware added before it (before routing, `request.scope["route"]` and path params are not available yet).
350
396
 
351
- WebSocket routes work the same way: the scope is bound to the `WebSocket` instead of a `Request`, and dependencies that ask for one get it. A websocket handed to a dependency shares its handshake with the one the route received, so it can be talked through after the route has called `accept()`:
397
+ WebSocket routes work the same way: the context is bound to the `WebSocket` instead of a `Request`, and dependencies that ask for one get it. A websocket handed to a dependency shares its handshake with the one the route received, so it can be talked through after the route has called `accept()`:
352
398
 
353
399
  ```python
354
400
  async def notify(websocket: WebSocket) -> None:
@@ -361,7 +407,7 @@ async def ws_route(websocket: WebSocket, service: Dep[Service]) -> None:
361
407
  await resolve(notify) # sends through the connection the route accepted
362
408
  ```
363
409
 
364
- Dependencies that take request parameters — `Header()`, `Cookie()`, `Query()`, `Path()`, and the body as `Body()`, `Form()`, `File()` or a pydantic model — resolve from the request the scope is bound to, exactly as they would in the route:
410
+ Dependencies that take request parameters — `Header()`, `Cookie()`, `Query()`, `Path()`, and the body as `Body()`, `Form()`, `File()` or a pydantic model — resolve from the request the context is bound to, exactly as they would in the route:
365
411
 
366
412
  ```python
367
413
  class Item(BaseModel):
@@ -392,24 +438,34 @@ async def handler(*, api_key: Annotated[str, Header()] = Injected) -> str:
392
438
  return api_key # a parameter has a name - `x-api-key`, as FastAPI derives it
393
439
  ```
394
440
 
395
- The body is read only when the resolved dependency declares one, and it is read once per request, shared with the route and every scope nested in it. When the route itself declares a body, dependencies see it in the shape the route gave it: a route with several body parameters embeds them under their names, and a dependency reads its own from there.
441
+ The body is read only when the resolved dependency declares one, and it is read once per request, shared with the route and every context nested in it. When the route itself declares a body, dependencies see it in the shape the route gave it: a route with several body parameters embeds them under their names, and a dependency reads its own from there.
396
442
 
397
- `push_inject_scope(request=...)` accepts either a `Request` or a `WebSocket`, and so does everything that reads `InjectScope.request` — the union is `fastapi_injected.types.BoundConnection`.
443
+ `injection_ctx(request=...)` accepts either a `Request` or a `WebSocket`, and so does everything that reads `InjectionContext.request` — the union is `fastapi_injected.types.BoundConnection`.
398
444
 
399
445
  ## What is public
400
446
 
401
- Everything the package supports is importable from `fastapi_injected` itself, and that is the surface a release keeps:
447
+ The root package is what you need to use the library, and the surface a release keeps:
402
448
 
403
449
  | | |
404
450
  | --- | --- |
405
- | Markers | `Dep`, `DepFactory`, `DepOf`, `Arg`, `Given`, `Injected` |
406
- | Resolving | `inject`, `resolve`, `bind_deps`, `signature_with_deps`, `remap_dep_args`, `clear_dependant_cache` |
407
- | Scopes and overrides | `InjectScope`, `push_inject_scope`, `inside_inject_scope`, `synthetic_request`, `push_overrides`, `Overrides`, `OverridesProvider`, `ValueOverride`, `FactoryOverride` |
408
- | Building on top | `MakeDataclass`, `MakeInjected`, `HasDependsHook`, `ArgMarker`, `is_arg`, `is_dep`, `unwrap_dep_tp`, `unwrap_dep_dependency` |
409
- | FastAPI integration | `add_injected_scope`, `init_inject_scope` |
410
- | Errors | `DependencyResolutionError`, `MissedDependencyError`, `MissingDependencyCacheError`, `NotADependencyError`, `UnboundDepArgsError`, `UnboundScopeError`, `UnnamedParamError` |
411
-
412
- `fastapi_injected.types` holds the typing vocabulary the signatures are written in — `DepReturn`, `DepShape`, `DepDecl`, `AsyncFunc`, `Coro` and friends — and is public too. Anything else, including every module whose name starts with an underscore, is machinery that can change in a patch release.
451
+ | Markers | `Dep`, `DepFactory`, `Arg`, `Given`, `Injected` |
452
+ | Resolving | `inject`, `resolve`, `bind_deps` |
453
+ | Contexts and overrides | `InjectionContext`, `injection_ctx`, `synthetic_request`, `push_overrides`, `override_app`, `ValueOverride`, `FactoryOverride` |
454
+ | FastAPI integration | `add_injection` |
455
+ | Errors | `DependencyResolutionError`, `NotADependencyError`, `UnboundContextError`, `UnnamedParamError` |
456
+
457
+ Code that builds on the library imports from the submodule that owns the piece. These are public too:
458
+
459
+ | Module | Names |
460
+ | --- | --- |
461
+ | `fastapi_injected.ext` | `MakeDataclass`, `MakeInjected`, `signature_with_deps`, `remap_dep_args`, `is_dep`, `is_arg`, `unwrap_dep_tp`, `unwrap_dep_dependency`, `strip_annotation`, `as_depends`, `clear_dependant_cache`, `ensure_injection_ctx`, `MissedDependencyError`, `UnboundDepArgsError` |
462
+ | `fastapi_injected.types` | `DepOf`, `ArgMarker`, `HasDependsHook`, and the typing vocabulary the signatures are written in — `DepReturn`, `DepShape`, `DepDecl`, `AsyncFunc`, `Coro`, `BoundConnection`, `DependencyCache` and friends |
463
+ | `fastapi_injected.overrides` | `Overrides`, `OverridesProvider` |
464
+ | `fastapi_injected.signature` | `Signature`, `ParamRole` |
465
+ | `fastapi_injected.fastapi` | `InjectionMiddleware`, `bind_injection_ctx`, `MissingDependencyCacheError` |
466
+ | `fastapi_injected.reflect` | `iter_dependant`, `iter_calls`, `iter_security`, `iter_params`, `find_dependant`, `iter_overridden`, `iter_routes`, `iter_api_routes`, `iter_routes_where`, `find_route`, `match_route`, `iter_routers`, `response_type`, `add_route_dependency`, `add_lifespan`, `iter_operations`, `operation_for`, `as_dependant` |
467
+
468
+ Anything else, including every module whose name starts with an underscore, is machinery that can change in a patch release.
413
469
 
414
470
  ## License
415
471
 
@@ -0,0 +1,33 @@
1
+ from ._bind import bind_deps
2
+ from ._given import Given
3
+ from .ctx import InjectionContext, UnboundContextError, injection_ctx, synthetic_request
4
+ from .deps import DependencyResolutionError, UnnamedParamError
5
+ from .fastapi import add_injection
6
+ from .inject import inject
7
+ from .overrides import FactoryOverride, ValueOverride, override_app, push_overrides
8
+ from .resolve import resolve
9
+ from .signature import NotADependencyError
10
+ from .types import Arg, Dep, DepFactory, Injected
11
+
12
+ __all__ = [
13
+ "Arg",
14
+ "Dep",
15
+ "DepFactory",
16
+ "DependencyResolutionError",
17
+ "FactoryOverride",
18
+ "Given",
19
+ "Injected",
20
+ "InjectionContext",
21
+ "NotADependencyError",
22
+ "UnboundContextError",
23
+ "UnnamedParamError",
24
+ "ValueOverride",
25
+ "add_injection",
26
+ "bind_deps",
27
+ "inject",
28
+ "injection_ctx",
29
+ "override_app",
30
+ "push_overrides",
31
+ "resolve",
32
+ "synthetic_request",
33
+ ]