From 61379dcf808869dcd9524a4bf0b66d53034288d5 Mon Sep 17 00:00:00 2001 From: Sai Mahesh sandeboina Date: Wed, 14 Jan 2026 22:33:30 -0500 Subject: [PATCH 1/2] Docs: clarify when to use async def vs def --- docs/en/docs/async.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/en/docs/async.md b/docs/en/docs/async.md index eac473bde4..79996d92c7 100644 --- a/docs/en/docs/async.md +++ b/docs/en/docs/async.md @@ -349,6 +349,10 @@ async def read_burgers(): return burgers ``` +**Clarification on `async def` usage** + +Using `async def` is beneficial only when the function performs asynchronous I/O operations, such as awaiting database calls, HTTP requests, or other non-blocking tasks. If a path operation function contains only blocking or CPU-bound code, defining it with `async def` does not provide performance benefits and may add unnecessary complexity. In those cases, using a regular `def` function is recommended. + ### More technical details { #more-technical-details } You might have noticed that `await` can only be used inside of functions defined with `async def`. From 43e8a1a619eddb1f658d8da039e0026f8a723092 Mon Sep 17 00:00:00 2001 From: Sai Mahesh sandeboina Date: Thu, 15 Jan 2026 15:02:08 -0500 Subject: [PATCH 2/2] Docs: refine async vs def clarification for I/O-bound work --- docs/en/docs/async.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/docs/async.md b/docs/en/docs/async.md index 79996d92c7..400ccd0e11 100644 --- a/docs/en/docs/async.md +++ b/docs/en/docs/async.md @@ -351,7 +351,8 @@ async def read_burgers(): **Clarification on `async def` usage** -Using `async def` is beneficial only when the function performs asynchronous I/O operations, such as awaiting database calls, HTTP requests, or other non-blocking tasks. If a path operation function contains only blocking or CPU-bound code, defining it with `async def` does not provide performance benefits and may add unnecessary complexity. In those cases, using a regular `def` function is recommended. +Using `async def` is beneficial primarily when the function performs I/O-bound work, such as awaiting network or disk operations (e.g. database calls, HTTP requests, or other non-blocking tasks). If a path operation function contains only blocking or CPU-bound code, defining it with `async def` does not provide performance benefits and may add unnecessary complexity. In such cases, using a regular `def` function is often simpler and clearer. + ### More technical details { #more-technical-details }