Codestin Search App

UltimateLobster · 2024-10-24T13:12:11Z

Support for lifespan scoped dependencies

This feature adds a scope to Depends: "lifespan".

If it is "lifespan" the dependency will be evaluated at the application startup (the value will be reused in all endpoints), and will be teared down at the application shutdown. It will be useful when defining db connections which need to be maintained and reused throughout the application's up-time:

def mongo_client():
    with MongoClient(SOME_CONNECTION_STRING) as client:
        yield client

ActiveMongoClient = mongo_client: Annotated[MongoClient, Depends(mongo_client, scope="lifespan")]

# A single instance of MongoClient will be evaluated when the application starts. That same instance will be used for all
# requests to both endpoints. When the application shuts down, that single instance will be cleaned up as well.

@app.post("/users")
def insert_user(
    mongo_client: ActiveMongoClient,
    username: str,  
) -> str:
    inserted_id = mongo_client["SomeDb"]["Users"].insert_one({"username": username})
    return user_id

@app.get("/users/{user_id}/username")
def get_username(
    mongo_client: ActiveMongoClient,
    user_id: Annotated[str, Path()],
) -> str:
    user = mongo_client["SomeDb"]["Users"].find_one({"_id": user_id})
    return user["username"]

The use_cache argument works in the same way for dependencies with "lifespan" scope as it is for dependencies with "request" or "function" scope:

def mongo_client():
    with MongoClient(SOME_CONNECTION_STRING) as client:
        yield client

DedicatedMongoConnection = mongo_client: Annotated[MongoClient, Depends(
    mongo_client, 
    scope="lifespan",
    use_cache=False
)]

# Each of these endpoints would have their own, dedicated mongo client which be reused for all requests to its respective endpoint. So overall, 2 instances will be created when the application starts. Those same 2 will be cleaned when the application shuts down.

@app.post("/users")
def insert_user(
    mongo_client: DedicatedMongoConnection ,
    username: str,  
) -> str:
    inserted_id = mongo_client["SomeDb"]["Users"].insert_one({"username": username})
    return user_id

@app.get("/users/{user_id}/username")
def get_username(
    mongo_client: DedicatedMongoConnection ,
    user_id: Annotated[str, Path()],
) -> str:
    user = mongo_client["SomeDb"]["Users"].find_one({"_id": user_id})
    return user["username"]

Implementation details to note:

There is a new, internal lifespan passed to the application's main router, which will be responsible to evaluate the dependencies.
If the user already has specified a lifespan argument, it will be merged with the internal lifespan using the recently added _merge_lifespan_context utility
Starlette forbids the use of startup/shutdown events in combination with the lifespan argument (if a lifespan is supplied, the events will never be handled). Since this PR makes it so we always have a lifespan arugment passed, it would've meant the on_event, on_startup and on_shutdown features would break. I solved it by manually calling them in the application's internal lifespan.
The lifespan scoped dependencies are gathered by iterating over each of the application's routes recursively. I added a property to APIRoutes which exposes this information, and updated the implementation of get_flat_dependent to concat dependencies as well.

Things left to do:

~~There are still tests missing from this PR which I'm still working on (Specifically, I need to add tests to cover interactions with websockets, as well as interactions with dependency overrides).~~
~~I still need to add the necessary documentation and examples.~~

…_scope argument.

…ure/lifespan-scoped-dependencies

…ed to the deprecated startup and shutdown events. Fixed bugs related to dependency duplcatation within the same router scope. Made more specific dependency related exceptions. Fixed some linting and mypy related issues.

…ure/lifespan-scoped-dependencies

…e with older python versions

…imateLobster/fastapi into feature/lifespan-scoped-dependencies

…ests which check websocket-scoped teardowns before the teardown actually happened on the server side.

…imateLobster/fastapi into feature/lifespan-scoped-dependencies

dolfinus · 2024-11-10T20:04:03Z

You can just create client instance, and then pass it to application endpoints using dependency_overrides:

app = FastAPI()
client = ...
app.dependency_overrides[MongoClient] = lambda: client

UltimateLobster · 2024-11-11T17:35:27Z

You can just create client instance, and then pass it to application endpoints using dependency_overrides:
app = FastAPI()
client = ...
app.dependency_overrides[MongoClient] = lambda: client

There are a few problems with this approach which this feature should be able to address:

The client is never cleaned up at the server shutdown or on a reload.
The creation of a resource during the import is problematic when you work with things like gunicorn, which may need to run the application in a separate process (There are clients which don't handle a fork of the connection object well).
The creation may need to be asynchronous which further complicates the ability to do so in the global scope.
Using dependency_overrides may lead to unexpected behavior when testing your application and one dependency overrides will take precedence over the other.
Dependencies defined with use_cache=False will still use the exact same client (they should have a separate client just for them).
When dealing with larger applications and lots of dependencies, it might be easy to forget to override the global dependency (since it's defined in a different place), and it will be a problem that might be harder to identify at the development stage since technically it will cause no errors.

Further discussion on the subject exists here.

…imateLobster/fastapi into feature/lifespan-scoped-dependencies

github-actions · 2024-11-23T19:21:35Z

📝 Docs preview for commit c7d4d10 at: https://29bab50f.fastapitiangolo.pages.dev

Modified Pages

https://29bab50f.fastapitiangolo.pages.dev/tutorial/dependencies/lifespan-scoped-dependencies/ - (before)

github-actions · 2025-10-11T16:50:22Z

This pull request has a merge conflict that needs to be resolved.

github-actions · 2025-10-23T20:35:58Z

This pull request has a merge conflict that needs to be resolved.

…imateLobster/fastapi into feature/lifespan-scoped-dependencies

…ompatibility anyways.

… and 3.9

…rage issues.

UltimateLobster · 2025-11-08T11:09:25Z

Updated the PR so it uses the new scope parameter added to Depends in version 0.121.0

github-actions · 2025-11-08T21:47:43Z

This pull request has a merge conflict that needs to be resolved.

YuriiMotov

@UltimateLobster, thank you for work you've done! Looks like you've put a lot of efforts into it!

This feature requires quite a lot of changes. So, let's first wait for Sebastian to validate the general idea.

YuriiMotov · 2025-11-13T20:03:49Z

+## The `use_cache` argument
+
+The `use_cache` argument works similarly to the way it worked with endpoint
+scoped dependencies. Meaning, as **FastAPI** gathers lifespan scoped dependencies, it
+will cache dependencies it already encountered before. However, you can disable
+this behavior by passing `use_cache=False` to `Depends`. This will cause a new lifespan
+dependency to be created for every endpoint/dependency/router where it shows up:


I think this is not correct. For other dependency scopes, use_cache works for this request only. Here, use_cache has different meaning.
I think for this reason new parameter should be introduced instead of use_cache. And passing use_cache should raise warning as it's useless.

Actually, I'm not sure it's needed.
Do you have any particular use cases for this option?

I guess I meant to say it works the same way for the respective scope. The relationship between the request dependencies and the request cache, is the same as between lifespan dependencies and lifespan cache. I should've found a better way to explain this.

As for its usefulness, I imagined a case of someone wanting a dedicated evaluation of the dependency. The example I gave in the documentation was a dedicated connection that was only used for requests of a certain route (which would usually require to create a new dependency function for that route).

But I agree it might be somewhat of a weak reason to support use_cache=False (along with wanting to allow a behavior that a reader of Depends's signature might expect).

If you think it would be better to disallow use_cache=False until a better argument arises, I won't mind doing it .

UltimateLobster · 2025-11-15T17:33:16Z

@UltimateLobster, thank you for work you've done! Looks like you've put a lot of efforts into it!

This feature requires quite a lot of changes. So, let's first wait for Sebastian to validate the general idea.

Thanks for taking a look at this!
I'm available to do whatever changes needed so this feature may get in. So hopefully Sebastian will like it :)

UltimateLobster and others added 3 commits October 24, 2024 15:30

Added support for lifespan-scoped dependencies using a new dependency…

25407d0

…_scope argument.

Merge branch 'master' of github.com:UltimateLobster/fastapi into feat…

65242e0

…ure/lifespan-scoped-dependencies

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

54ecfb8

UltimateLobster mentioned this pull request Oct 24, 2024

Further develop startup and shutdown events #617

Closed

svlandeg added the feature New feature or request label Oct 25, 2024

UltimateLobster and others added 17 commits November 9, 2024 09:22

Merge branch 'master' of github.com:UltimateLobster/fastapi into feat…

7614cc7

…ure/lifespan-scoped-dependencies

Resolved conflicts

e94b599

Applied ruff linting

d512b03

Fixed tests compatibility with older python versions

e7ab957

Fixed import of assert_never from typing

3c5aeaa

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

9f2bd41

Fixed usage of warnings.catch_warnings in a way that is not compatibl…

6c923ac

…e with older python versions

Merge branch 'feature/lifespan-scoped-dependencies' of github.com:Ult…

6572e90

…imateLobster/fastapi into feature/lifespan-scoped-dependencies

Fixed tests compatibility with python 3.8

d38364a

Fixed tests having incorrect ids. Fixed an inconsistent results for t…

3b27561

…ests which check websocket-scoped teardowns before the teardown actually happened on the server side.

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

179d653

Added coverage

01e9da1

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

f9ca77e

Fixed more linting

8a5c3fe

Merge branch 'feature/lifespan-scoped-dependencies' of github.com:Ult…

adb42f4

…imateLobster/fastapi into feature/lifespan-scoped-dependencies

Yet another coverage fixes

33f766a

UltimateLobster and others added 5 commits November 16, 2024 16:35

Merge branch 'fastapi:master' into feature/lifespan-scoped-dependencies

933bfe3

Added documentation for lifespan scoped dependencies

01dc24e

Merge branch 'fastapi:master' into feature/lifespan-scoped-dependencies

09ae29a

Merge branch 'feature/lifespan-scoped-dependencies' of github.com:Ult…

09d9fc5

…imateLobster/fastapi into feature/lifespan-scoped-dependencies

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

c7d4d10

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Oct 11, 2025

Resolved conflicts.

452b729

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Oct 11, 2025

UltimateLobster added 2 commits October 14, 2025 13:04

Merge branch 'master' into feature/lifespan-scoped-dependencies

4bd908f

Merge branch 'master' into feature/lifespan-scoped-dependencies

695a3b5

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Oct 23, 2025

UltimateLobster and others added 3 commits November 8, 2025 10:47

Resolved conflicts.

8867184

Merge branch 'feature/lifespan-scoped-dependencies' of github.com:Ult…

a5e8122

…imateLobster/fastapi into feature/lifespan-scoped-dependencies

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

b189030

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Nov 8, 2025

UltimateLobster and others added 6 commits November 8, 2025 11:09

Exported some duplicated logic into a common _BaseDependant.

8ca1364

Removed backwards compatibility since it doesn't actually preserves c…

e563b87

…ompatibility anyways.

Fixed some linting and python 3.8 compatibility issues.

c0ad39e

Fixed linting.

f344645

Resolved conflicts.

8dcdd77

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

e39ad15

UltimateLobster changed the title ~~Add dependency_scope arguments to Depends in order to support lifespan scoped dependencies.~~ Add lifespan dependency scope Nov 8, 2025

UltimateLobster and others added 3 commits November 8, 2025 11:50

Removed kw_only from dataclass since it's not supported in python 3.8…

a4984b8

… and 3.9

Updated the lifespan-scoped-dependencies tutorial and fixed some cove…

f1b5323

…rage issues.

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

d9b66d1

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Nov 8, 2025

YuriiMotov reviewed Nov 13, 2025

View reviewed changes

YuriiMotov changed the title ~~Add lifespan dependency scope~~ ✨ Add lifespan dependency scope Nov 13, 2025

YuriiMotov mentioned this pull request Mar 12, 2026

feat: add dependency_scope="lifespan" for application-lifetime depend… #15097

Open

This comment was marked as spam.

Sign in to view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

✨ Add `lifespan` dependency scope#12529

✨ Add `lifespan` dependency scope#12529
UltimateLobster wants to merge 57 commits into
fastapi:masterfrom
UltimateLobster:feature/lifespan-scoped-dependencies

UltimateLobster commented Oct 24, 2024 •

edited

Loading

Uh oh!

dolfinus commented Nov 10, 2024 •

edited

Loading

Uh oh!

UltimateLobster commented Nov 11, 2024

Uh oh!

github-actions Bot commented Nov 23, 2024

Uh oh!

github-actions Bot commented Oct 11, 2025

Uh oh!

github-actions Bot commented Oct 23, 2025

Uh oh!

UltimateLobster commented Nov 8, 2025

Uh oh!

github-actions Bot commented Nov 8, 2025

Uh oh!

YuriiMotov left a comment •

edited

Loading

Uh oh!

YuriiMotov Nov 13, 2025

Uh oh!

UltimateLobster Nov 15, 2025

Uh oh!

UltimateLobster commented Nov 15, 2025

Uh oh!

This comment was marked as spam.

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

Conversation

UltimateLobster commented Oct 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Support for lifespan scoped dependencies

Implementation details to note:

Things left to do:

Uh oh!

dolfinus commented Nov 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

UltimateLobster commented Nov 11, 2024

Uh oh!

github-actions Bot commented Nov 23, 2024

Modified Pages

Uh oh!

github-actions Bot commented Oct 11, 2025

Uh oh!

github-actions Bot commented Oct 23, 2025

Uh oh!

UltimateLobster commented Nov 8, 2025

Uh oh!

github-actions Bot commented Nov 8, 2025

Uh oh!

YuriiMotov left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YuriiMotov Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

UltimateLobster Nov 15, 2025

Choose a reason for hiding this comment

Uh oh!

UltimateLobster commented Nov 15, 2025

Uh oh!

This comment was marked as spam.

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

UltimateLobster commented Oct 24, 2024 •

edited

Loading

dolfinus commented Nov 10, 2024 •

edited

Loading

YuriiMotov left a comment •

edited

Loading