Dependencies with yield (used as context managers)

[tiangolo]

Add support for context manager dependencies using functions with yield. Sync or async.

With inspiration from @dmontagu 's #570.

This handles dependencies that yield by converting them into a sync or async context manager, depending on the function. And runs them in a "context manager stack".

This way, the order of dependencies is preserved and cleanup/closing happens in the correct order (the first dependency called is cleaned last).

This also means that dependencies that require other dependencies will still have them on scope during cleanup. So, contextmanager-style dependencies that require other contextmanager dependencies will have access to them during cleanup.

When a dependency function is a normal function (not async), the context manager is called in a threadpool (__enter__), so, the same as with normal dependencies, it's safe to do non-async blocking IO in contextmanager style dependencies. E.g. start a DB connection, probably the main use-case for this. And the same for cleaning it up (__exit__).

This works by default in Python 3.7.

And works in Python 3.6 if the backports are installed:

• async-exit-stack
• async-generator

pip install async-exit-stack async-generator

But they are not forced/required dependencies. If an app doesn't use context managers and still runs in Python 3.6, it will still work without the backports.

...Although I suspect most of the apps will use this for DB connections.

These backport dependencies are checked on app initialization, so, if a contextmanager-style dependency function (with yields) is found, the environment is not Python 3.7+, and the backports are not installed, it will raise a RuntimeError right away on app initialization (so, no risk for the error lurking into a prod environment).

---

TODO:

• Fix mypy types.
• Extend tests to check for correct order of contextmanager dependencies with subdependencies.
• Extend tests to verify that background tasks can still access the dependencies from context managers (e.g. DB connections).
• Add docs.

[dmontagu]

This is looking really great!

[codecov]

Codecov Report

Merging #595 into master will not change coverage.
The diff coverage is 100%.

@@          Coverage Diff           @@
##           master   #595    +/-   ##
======================================
  Coverage     100%   100%            
======================================
  Files         264    269     +5     
  Lines        6429   6823   +394     
======================================
+ Hits         6429   6823   +394

Impacted Files	Coverage Δ
docs/src/sql_databases/sql_app/main.py	100% <100%> (ø)	⬆️
...est_sql_databases/test_sql_databases_middleware.py	100% <100%> (ø)
..._tutorial/test_sql_databases/test_sql_databases.py	100% <100%> (ø)	⬆️
fastapi/applications.py	100% <100%> (ø)	⬆️
tests/test_fakeasync.py	100% <100%> (ø)
fastapi/concurrency.py	100% <100%> (ø)
fastapi/dependencies/utils.py	100% <100%> (ø)	⬆️
docs/src/sql_databases/sql_app/alt_main.py	100% <100%> (ø)
tests/test_dependency_contextmanager.py	100% <100%> (ø)
... and 4 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b65be5d...553f503. Read the comment docs.

[tiangolo]

@dmontagu this is ready. 🚀 🎉

I used some sections from your original PR 😅

Do you wanna give it a last check before I merge?

[dmontagu]

Mostly just minor docs fixes. Some are typos, some are more opinion-based; feel free to ignore anything you disagree with!

[tiangolo]

Thanks a lot for the thorough review @dmontagu ! You have an eagle eye! 🦅 🔍 🕵️‍♂️