From 007608519506dc74f6c78254672dfe59cf9bb5ac Mon Sep 17 00:00:00 2001 From: JP-Ellis Date: Wed, 5 Mar 2025 19:04:57 +1100 Subject: [PATCH 1/2] docs: add caveat about ContextVar in dependencies As discovered and discussed in #13382, ContextVars set in a _synchronous_ dependency is not available to the rest of the request due to the way FastAPI handles that dependency. The documentation did not make any mention of this, and it was only after I asked that I discovered this was intended behaviour. So I am updating the docs to make this clear to others. Ref: #13382 Signed-off-by: JP-Ellis --- docs/en/docs/tutorial/dependencies/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/en/docs/tutorial/dependencies/index.md b/docs/en/docs/tutorial/dependencies/index.md index 596ce1599..1bab8ece3 100644 --- a/docs/en/docs/tutorial/dependencies/index.md +++ b/docs/en/docs/tutorial/dependencies/index.md @@ -156,6 +156,12 @@ If you don't know, check the [Async: *"In a hurry?"*](../../async.md#in-a-hurry) /// +/// warning + +If you need to rely on `ContextVar` values across multiple steps in a request, **use an async dependency** or another approach. This is because sync dependencies are executed in the mainthread*, while `async` dependencies run in the same thread pool as the one handling the request. As `ContextVar` provides thread-local storage, any value set inside a sync dependency will not be available in the rest of the request handling. + +/// + ## Integrated with OpenAPI All the request declarations, validations and requirements of your dependencies (and sub-dependencies) will be integrated in the same OpenAPI schema. From bcde4ab4a57d9443cd82a02e311c22d30ef6d2eb Mon Sep 17 00:00:00 2001 From: JP-Ellis Date: Wed, 5 Mar 2025 20:05:25 +1100 Subject: [PATCH 2/2] docs: translate contextvar warning Signed-off-by: JP-Ellis --- docs/de/docs/tutorial/dependencies/index.md | 6 ++++++ docs/es/docs/tutorial/dependencies/index.md | 6 ++++++ docs/ja/docs/tutorial/dependencies/index.md | 6 ++++++ docs/ko/docs/tutorial/dependencies/index.md | 6 ++++++ docs/pt/docs/tutorial/dependencies/index.md | 6 ++++++ docs/ru/docs/tutorial/dependencies/index.md | 6 ++++++ docs/zh/docs/tutorial/dependencies/index.md | 12 ++++++++++++ 7 files changed, 48 insertions(+) diff --git a/docs/de/docs/tutorial/dependencies/index.md b/docs/de/docs/tutorial/dependencies/index.md index 42182d030..1387604ca 100644 --- a/docs/de/docs/tutorial/dependencies/index.md +++ b/docs/de/docs/tutorial/dependencies/index.md @@ -155,6 +155,12 @@ Wenn Ihnen das nichts sagt, lesen Sie den [Async: *„In Eile?“*](../../async. /// +/// warning | Warnung + +Wenn du dich über mehrere Schritte in einer Anfrage hinweg auf `ContextVar`-Werte verlassen musst, **verwende eine async-Abhängigkeit** oder einen anderen Ansatz. Dies liegt daran, dass synchrone Abhängigkeiten im Hauptthread ausgeführt werden, während `async`-Abhängigkeiten im selben Thread-Pool wie derjenige, der die Anfrage bearbeitet, ausgeführt werden. Da `ContextVar` thread-lokalen Speicher bereitstellt, sind alle Werte, die innerhalb einer synchronen Abhängigkeit gesetzt werden, im restlichen Anfrageverlauf nicht verfügbar. + +/// + ## Integriert in OpenAPI Alle Requestdeklarationen, -validierungen und -anforderungen Ihrer Abhängigkeiten (und Unterabhängigkeiten) werden in dasselbe OpenAPI-Schema integriert. diff --git a/docs/es/docs/tutorial/dependencies/index.md b/docs/es/docs/tutorial/dependencies/index.md index 2fb060177..6bc699ade 100644 --- a/docs/es/docs/tutorial/dependencies/index.md +++ b/docs/es/docs/tutorial/dependencies/index.md @@ -156,6 +156,12 @@ Si no lo sabes, revisa la sección [Async: *"¿Con prisa?"*](../../async.md#in-a /// +/// warning | Advertencia + +Si necesitas depender de valores de `ContextVar` a lo largo de múltiples pasos en una solicitud, **usa una dependencia async** u otro enfoque. Esto se debe a que las dependencias sync se ejecutan en el hilo principal, mientras que las dependencias `async` se ejecutan en el mismo grupo de hilos que maneja la solicitud. Como `ContextVar` proporciona almacenamiento local de hilos, cualquier valor establecido dentro de una dependencia sync no estará disponible en el resto del manejo de la solicitud. + +/// + ## Integración con OpenAPI Todas las declaraciones de request, validaciones y requisitos de tus dependencias (y sub-dependencias) se integrarán en el mismo esquema de OpenAPI. diff --git a/docs/ja/docs/tutorial/dependencies/index.md b/docs/ja/docs/tutorial/dependencies/index.md index c2b5e7bba..4a0b3a1b1 100644 --- a/docs/ja/docs/tutorial/dependencies/index.md +++ b/docs/ja/docs/tutorial/dependencies/index.md @@ -118,6 +118,12 @@ common_parameters --> read_users /// +/// warning | 警告 + +リクエストの複数のステップにわたって `ContextVar` 値に依存する必要がある場合は、**async 依存関係**または他のアプローチを使用してください。これは、同期依存関係がメインスレッドで実行されるのに対し、`async` 依存関係はリクエストを処理するのと同じスレッドプールで実行されるためです。`ContextVar` はスレッドローカルストレージを提供するため、同期依存関係内で設定された値はリクエスト処理の残りの部分では利用できません。 + +/// + ## OpenAPIとの統合 依存関係（およびサブ依存関係）のすべてのリクエスト宣言、検証、および要件は、同じOpenAPIスキーマに統合されます。 diff --git a/docs/ko/docs/tutorial/dependencies/index.md b/docs/ko/docs/tutorial/dependencies/index.md index b35a41e37..e5b90d49a 100644 --- a/docs/ko/docs/tutorial/dependencies/index.md +++ b/docs/ko/docs/tutorial/dependencies/index.md @@ -156,6 +156,12 @@ commons: Annotated[dict, Depends(common_parameters)] /// +/// warning | 경고 + +요청의 여러 단계에 걸쳐 `ContextVar` 값을 사용해야 하는 경우, **async 종속성** 또는 다른 접근 방식을 사용하세요. 이는 동기 종속성이 메인 스레드에서 실행되는 반면, `async` 종속성은 요청을 처리하는 동일한 스레드 풀에서 실행되기 때문입니다. `ContextVar`는 스레드 로컬 저장소를 제공하므로, 동기 종속성 내에서 설정된 값은 요청 처리의 나머지 부분에서 사용할 수 없습니다. + +/// + ## OpenAPI와 통합 모든 요청 선언, 검증과 의존성(및 하위 의존성)에 대한 요구 사항은 동일한 OpenAPI 스키마에 통합됩니다. diff --git a/docs/pt/docs/tutorial/dependencies/index.md b/docs/pt/docs/tutorial/dependencies/index.md index 1500b715a..c8b98fba1 100644 --- a/docs/pt/docs/tutorial/dependencies/index.md +++ b/docs/pt/docs/tutorial/dependencies/index.md @@ -156,6 +156,12 @@ Caso você não conheça, veja em [Async: *"Com Pressa?"*](../../async.md#com-pr /// +/// warning | Aviso + +Se você precisar depender de valores de `ContextVar` em várias etapas de uma solicitação, **use uma dependência async** ou outra abordagem. Isso ocorre porque as dependências síncronas são executadas no thread principal, enquanto as dependências `async` são executadas no mesmo pool de threads que está lidando com a solicitação. Como `ContextVar` fornece armazenamento local de threads, qualquer valor definido dentro de uma dependência síncrona não estará disponível no restante do manuseio da solicitação. + +/// + ## Integrando com OpenAPI Todas as declarações de requisições, validações e requisitos para suas dependências (e sub-dependências) serão integradas em um mesmo esquema OpenAPI. diff --git a/docs/ru/docs/tutorial/dependencies/index.md b/docs/ru/docs/tutorial/dependencies/index.md index 28790bd5a..3e22fda65 100644 --- a/docs/ru/docs/tutorial/dependencies/index.md +++ b/docs/ru/docs/tutorial/dependencies/index.md @@ -150,6 +150,12 @@ commons: Annotated[dict, Depends(common_parameters)] /// +/// warning | Предупреждение + +Если вам нужно полагаться на значения `ContextVar` на нескольких этапах запроса, **используйте async зависимость** или другой подход. Это связано с тем, что синхронные зависимости выполняются в основном потоке, в то время как `async` зависимости выполняются в том же пуле потоков, что и обработка запроса. Поскольку `ContextVar` предоставляет локальное хранилище для потоков, любые значения, установленные внутри синхронной зависимости, не будут доступны в остальной части обработки запроса. + +/// + ## Интеграция с OpenAPI Все заявления о запросах, валидаторы, требования ваших зависимостей (и подзависимостей) будут интегрированы в соответствующую OpenAPI-схему. diff --git a/docs/zh/docs/tutorial/dependencies/index.md b/docs/zh/docs/tutorial/dependencies/index.md index 9eec69ed5..1c2a6e3a5 100644 --- a/docs/zh/docs/tutorial/dependencies/index.md +++ b/docs/zh/docs/tutorial/dependencies/index.md @@ -118,6 +118,18 @@ common_parameters --> read_users /// +/// note | 笔记 + +如果你不知道，请查看文档中关于 `async` 和 `await` 的 [Async: *"赶时间？"*](../../async.md#in-a-hurry){.internal-link target=_blank} 部分。 + +/// + +/// warning | 警告 + +如果你需要在请求的多个步骤中依赖 `ContextVar` 值，**使用 async 依赖**或其他方法。这是因为同步依赖在主线程中执行，而 `async` 依赖在处理请求的同一线程池中运行。由于 `ContextVar` 提供线程本地存储，在同步依赖中设置的任何值在请求处理的其余部分中将不可用。 + +/// + ## 与 OpenAPI 集成 依赖项及子依赖项的所有请求声明、验证和需求都可以集成至同一个 OpenAPI 概图。