Fastapi: Clarify run_in_threadpool magic

[haizaar]

Good day,

First of all - many thanks for creating this project. Such a relief - you really nailed the proper amount of "batteries included". And docs are great - not a given thing for such a young project.

I'm studying SQL Database example where you note that SQLAlchemy is not compatible with async hence you configure path using def instead of async def. However this example raises and eyebrow because it should block the whole server while database is executing - only that it does not because the magic you do by running request handlers through threadpool unless they are co-routines.

While this magic is nice convenience, don't you think I can confuse users, particularly those who are less experienced with the whole sync/async co-existence semantics in Python world?

My bottom line is that IMHO it worth adding a clear "Unless you define your request handlers as coroutines FastAPI will run them them in separate thread" note in the "SQL Databases" and "Concurrency and async / await" chapters. What do you think?

Me coming from aiohttp is used to have non-async request handlers for simple methods that don't involve any IO and this magical FastAPI behavior, while useful, would've caused a performance penalty on those methods.

[tiangolo]

First of all - many thanks for creating this project. Such a relief - you really nailed the proper amount of "batteries included". And docs are great - not a given thing for such a young project.

That's great to hear! Thanks :blush:

[...] adding a clear "Unless you define your request handlers as coroutines FastAPI will run them in separate thread"

Fair point. I'll add it as a "technical detail".

---

I don't expect a lot of people to deeply understand how this thread-related stuff works, or to need to understand it to be able to use FastAPI.

But not making it explicit might be confusing for more experienced developers like you, that can understand the fine details of when to async or not.

[tiangolo]

Done :heavy_check_mark:

The new docs section is here: https://fastapi.tiangolo.com/async/#very-technical-details