Merge branch 'master' into redoc-params

docs/en/docs/release-notes.md

@@ -7,6 +7,10 @@ hide:
 
 ## Latest Changes
 
+### Refactors
+
+* ♻️ Update tests and internals for compatibility with Pydantic >=2.10. PR [#12971](https://github.com/fastapi/fastapi/pull/12971) by [@tamird](https://github.com/tamird).
+
 ### Docs
 
 * 📝 Update includes format in docs with an automated script. PR [#12950](https://github.com/fastapi/fastapi/pull/12950) by [@tiangolo](https://github.com/tiangolo).
@@ -15,6 +19,7 @@ hide:
 
 ### Translations
 
+* 🌐 Add Korean translation for `docs/ko/docs/tutorial/query-param-models.md`. PR [#12940](https://github.com/fastapi/fastapi/pull/12940) by [@jts8257](https://github.com/jts8257).
 * 🔥 Remove obsolete tutorial translation to Chinese for `docs/zh/docs/tutorial/sql-databases.md`, it references files that are no longer on the repo. PR [#12949](https://github.com/fastapi/fastapi/pull/12949) by [@tiangolo](https://github.com/tiangolo).
 
 ### Internal

docs/ko/docs/tutorial/query-param-models.md

@@ -0,0 +1,68 @@
+# 쿼리 매개변수 모델
+
+연관된 쿼리 **매개변수** 그룹이 있다면 **Pydantic 모델** 을 사용해 선언할 수 있습니다.
+
+이렇게 하면 **여러 곳**에서 **모델을 재사용**할 수 있을 뿐만 아니라, 매개변수에 대한 검증 및 메타데이터도 한 번에 선언할 수 있습니다. 😎
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.115.0`부터 제공됩니다. 🤓
+
+///
+
+## 쿼리 매개변수와 Pydantic 모델
+
+필요한 **쿼리 매개변수**를 **Pydantic 모델** 안에 선언한 다음, 모델을 `Query`로 선언합니다.
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI**는 요청의 **쿼리 매개변수**에서 **각 필드**의 데이터를 **추출**해 정의한 Pydantic 모델로 제공합니다.
+
+## 문서 확인하기
+
+`/docs` 경로의 API 문서에서 매개변수를 확인할 수 있습니다.
+
+<div class="screenshot">
+<img src="/img/tutorial/query-param-models/image01.png">
+</div>
+
+## 추가 쿼리 매개변수 금지
+
+몇몇의 특이한 경우에 (흔치 않지만), 허용할 쿼리 매개변수를 **제한**해야할 수 있습니다.
+
+Pydantic 모델 설정에서 `extra` 필드를 `forbid` 로 설정할 수 있습니다.
+
+{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}
+
+만약 클라이언트가 쿼리 매개변수로 **추가적인** 데이터를 보내려고 하면, 클라이언트는 **에러** 응답을 받게 됩니다.
+
+예를 들어, 아래와 같이 만약 클라이언트가 `tool` 쿼리 매개변수에 `plumbus` 라는 값을 추가해서 보내려고 하면,
+
+```http
+https://example.com/items/?limit=10&tool=plumbus
+```
+
+클라이언트는 쿼리 매개변수 `tool` 이 허용되지 않는다는 **에러** 응답을 받게 됩니다.
+
+```json
+{
+    "detail": [
+        {
+            "type": "extra_forbidden",
+            "loc": ["query", "tool"],
+            "msg": "Extra inputs are not permitted",
+            "input": "plumbus"
+        }
+    ]
+}
+```
+
+## 요약
+
+**FastAPI** 에서 **쿼리 매개변수** 를 선언할 때 **Pydantic 모델** 을 사용할 수 있습니다. 😎
+
+/// tip | 팁
+
+스포일러 경고: Pydantic 모델을 쿠키와 헤더에도 적용할 수 있습니다. 이에 대해서는 이후 튜토리얼에서 다룰 예정입니다. 🤫
+
+///

fastapi/_compat.py

@@ -21,12 +21,10 @@ from typing import (
 from fastapi.exceptions import RequestErrorModel
 from fastapi.types import IncEx, ModelNameMap, UnionType
 from pydantic import BaseModel, create_model
-from pydantic.version import VERSION as P_VERSION
+from pydantic.version import VERSION as PYDANTIC_VERSION
 from starlette.datastructures import UploadFile
 from typing_extensions import Annotated, Literal, get_args, get_origin
 
-# Reassign variable to make it reexported for mypy
-PYDANTIC_VERSION = P_VERSION
 PYDANTIC_VERSION_MINOR_TUPLE = tuple(int(x) for x in PYDANTIC_VERSION.split(".")[:2])
 PYDANTIC_V2 = PYDANTIC_VERSION_MINOR_TUPLE[0] == 2
 
@@ -47,6 +45,8 @@ sequence_annotation_to_type = {
 
 sequence_types = tuple(sequence_annotation_to_type.keys())
 
+Url: Type[Any]
+
 if PYDANTIC_V2:
     from pydantic import PydanticSchemaGenerationError as PydanticSchemaGenerationError
     from pydantic import TypeAdapter

tests/test_tutorial/test_query_params_str_validations/test_tutorial010.py

@@ -1,5 +1,6 @@
 import pytest
 from dirty_equals import IsDict
+from fastapi._compat import PYDANTIC_VERSION_MINOR_TUPLE
 from fastapi.testclient import TestClient
 
 
@@ -107,6 +108,12 @@ def test_openapi_schema(client: TestClient):
                                     ],
                                     "title": "Query string",
                                     "description": "Query string for the items to search in the database that have a good match",
+                                    # See https://github.com/pydantic/pydantic/blob/80353c29a824c55dea4667b328ba8f329879ac9f/tests/test_fastapi.sh#L25-L34.
+                                    **(
+                                        {"deprecated": True}
+                                        if PYDANTIC_VERSION_MINOR_TUPLE >= (2, 10)
+                                        else {}
+                                    ),
                                 }
                             )
                             | IsDict(

tests/test_tutorial/test_query_params_str_validations/test_tutorial010_an.py

@@ -1,5 +1,6 @@
 import pytest
 from dirty_equals import IsDict
+from fastapi._compat import PYDANTIC_VERSION_MINOR_TUPLE
 from fastapi.testclient import TestClient
 
 
@@ -107,6 +108,12 @@ def test_openapi_schema(client: TestClient):
                                     ],
                                     "title": "Query string",
                                     "description": "Query string for the items to search in the database that have a good match",
+                                    # See https://github.com/pydantic/pydantic/blob/80353c29a824c55dea4667b328ba8f329879ac9f/tests/test_fastapi.sh#L25-L34.
+                                    **(
+                                        {"deprecated": True}
+                                        if PYDANTIC_VERSION_MINOR_TUPLE >= (2, 10)
+                                        else {}
+                                    ),
                                 }
                             )
                             | IsDict(

tests/test_tutorial/test_query_params_str_validations/test_tutorial010_an_py310.py

@@ -1,5 +1,6 @@
 import pytest
 from dirty_equals import IsDict
+from fastapi._compat import PYDANTIC_VERSION_MINOR_TUPLE
 from fastapi.testclient import TestClient
 
 from ...utils import needs_py310
@@ -114,6 +115,12 @@ def test_openapi_schema(client: TestClient):
                                     ],
                                     "title": "Query string",
                                     "description": "Query string for the items to search in the database that have a good match",
+                                    # See https://github.com/pydantic/pydantic/blob/80353c29a824c55dea4667b328ba8f329879ac9f/tests/test_fastapi.sh#L25-L34.
+                                    **(
+                                        {"deprecated": True}
+                                        if PYDANTIC_VERSION_MINOR_TUPLE >= (2, 10)
+                                        else {}
+                                    ),
                                 }
                             )
                             | IsDict(

tests/test_tutorial/test_query_params_str_validations/test_tutorial010_an_py39.py

@@ -1,5 +1,6 @@
 import pytest
 from dirty_equals import IsDict
+from fastapi._compat import PYDANTIC_VERSION_MINOR_TUPLE
 from fastapi.testclient import TestClient
 
 from ...utils import needs_py39
@@ -114,6 +115,12 @@ def test_openapi_schema(client: TestClient):
                                     ],
                                     "title": "Query string",
                                     "description": "Query string for the items to search in the database that have a good match",
+                                    # See https://github.com/pydantic/pydantic/blob/80353c29a824c55dea4667b328ba8f329879ac9f/tests/test_fastapi.sh#L25-L34.
+                                    **(
+                                        {"deprecated": True}
+                                        if PYDANTIC_VERSION_MINOR_TUPLE >= (2, 10)
+                                        else {}
+                                    ),
                                 }
                             )
                             | IsDict(

tests/test_tutorial/test_query_params_str_validations/test_tutorial010_py310.py

@@ -1,5 +1,6 @@
 import pytest
 from dirty_equals import IsDict
+from fastapi._compat import PYDANTIC_VERSION_MINOR_TUPLE
 from fastapi.testclient import TestClient
 
 from ...utils import needs_py310
@@ -114,6 +115,12 @@ def test_openapi_schema(client: TestClient):
                                     ],
                                     "title": "Query string",
                                     "description": "Query string for the items to search in the database that have a good match",
+                                    # See https://github.com/pydantic/pydantic/blob/80353c29a824c55dea4667b328ba8f329879ac9f/tests/test_fastapi.sh#L25-L34.
+                                    **(
+                                        {"deprecated": True}
+                                        if PYDANTIC_VERSION_MINOR_TUPLE >= (2, 10)
+                                        else {}
+                                    ),
                                 }
                             )
                             | IsDict(