Description

This PR clarifies the misleading "async Technical Details" note in the UploadFile documentation.

File: docs/en/docs/tutorial/request-files.md
https://github.com/fastapi/fastapi/blob/master/docs/en/docs/tutorial/request-files.md

Current Issue

The current note states:

"When you use the async methods, FastAPI runs the file methods in a threadpool and awaits for them."

While technically accurate, this is misleading because:

1. It doesn't explain why threadpool is necessary
2. It implies ALL async operations use threadpools (contradicting async/await principles)
3. It lacks context about the actual benefit: maintaining event loop concurrency

Solution

The updated note now explains:

• Why: Threadpool is used to make blocking file I/O operations non-blocking
• Benefit: Allows the async event loop to process other requests while file operations are in progress
• Context: This is a special case for blocking I/O, not the norm for async operations

Technical Background

Evidence from source code (fastapi/datastructures.py):
Each async method has a docstring: "To be awaitable, compatible with async, this is run in threadpool."

Evidence from documentation (docs/en/docs/async.md, line 418):
FastAPI explicitly states threadpool is used for def functions, implying async def should NOT use threadpool except for blocking I/O (which requires special handling).

New Text

/// note | `async` Technical Details

The `UploadFile` async methods wrap blocking file I/O operations and run them in a threadpool to make them non-blocking. This allows the async event loop to process other requests while file operations are in progress, which is essential for maintaining the non-blocking nature of your `async def` path operation functions.

///