Browse Source

Reworded some sections and fixed certain formatting issues

pull/12529/head
Nir Schulman 8 months ago
parent
commit
df180870b1
  1. 50
      docs/en/docs/tutorial/dependencies/lifespan-scoped-dependencies.md

50
docs/en/docs/tutorial/dependencies/lifespan-scoped-dependencies.md

@ -1,24 +1,34 @@
# Lifespan Scoped Dependencies
## Intro
So far we've used dependencies which are "endpoint scoped". Meaning, they are
called again and again for every incoming request to the endpoint. However,
this is not ideal for all kinds of dependencies.
this is not always ideal:
* Sometimes dependencies have a large setup/teardown time. Running it for every request will result in bad performance.
* Sometimes dependencies need to have their values shared throughout the lifespan
of the application between multiple requests.
Sometimes dependencies have a large setup/teardown time, or there is a need
for their value to be shared throughout the lifespan of the application. An
example of this would be a connection to a database. Databases are typically
An example of this would be a connection to a database. Databases are typically
less efficient when working with lots of connections and would prefer that
clients would create a single connection for their operations.
For such cases, you might want to use "lifespan scoped" dependencies.
For such cases can be solved by using "lifespan scoped dependencies".
## Intro
Lifespan scoped dependencies work similarly to the dependencies we've worked
with so far (which are endpoint scoped). However, they are called once and only
once in the application's lifespan (instead of being called again and again for
every request). The returned value will be shared across all requests that need
it.
## What is a lifespan scoped dependency?
Lifespan scoped dependencies work similarly to the (endpoint scoped)
dependencies we've worked with so far. However, unlike endpoint scoped
dependencies, lifespan scoped dependencies are called once and only
once in the application's lifespan:
* During the application startup process, all lifespan scoped dependencies will
be called.
* Their returned value will be shared across all requests to the application.
* During the application's shutdown process, all lifespan scoped dependencies
will be gracefully teared down.
## Create a lifespan scoped dependency
@ -56,12 +66,12 @@ this behavior by passing `use_cache=False` to `Depends`:
In this example, the `read_users` and `read_groups` endpoints are using
`use_cache=False` whereas the `read_items` and `read_item` are using
`use_cache=True`. That means that we'll have a total of 3 connections created
for the duration of the application's lifespan. One connection will be shared
across all requests for the `read_items` and `read_item` endpoints. A second
connection will be shared across all requests for the `read_users` endpoint. The
third and final connection will be shared across all requests for the
`read_groups` endpoint.
`use_cache=True`.
That means that we'll have a total of 3 connections created
for the duration of the application's lifespan:
* One connection will be shared across all requests for the `read_items` and `read_item` endpoints.
* A second connection will be shared across all requests for the `read_users` endpoint.
* A third and final connection will be shared across all requests for the `read_groups` endpoint.
## Lifespan Scoped Sub-Dependencies
@ -92,8 +102,8 @@ Therefore, it is not possible for a lifespan scoped dependency to use any
parameters that require the scope of an endpoint.
That includes but not limited to:
* Parts of the request (like `Body`, `Query` and `Path`)
* The request/response objects themselves (like `Request`, `Response` and `WebSocket`)
* Endpoint scoped sub-dependencies.
* Parts of the request (like `Body`, `Query` and `Path`)
* The request/response objects themselves (like `Request`, `Response` and `WebSocket`)
* Endpoint scoped sub-dependencies.
Defining a dependency with such parameters will raise an `InvalidDependencyScope` error.

Loading…
Cancel
Save