✨ Support providing serializing context to response models

.github/workflows/test.yml

@@ -54,7 +54,7 @@ jobs:
           - "3.10"
           - "3.9"
           - "3.8"
-        pydantic-version: ["pydantic-v1", "pydantic-v2"]
+        pydantic-version: ["pydantic-v1", "pydantic-v2.7", "pydantic-v2.8+"]
       fail-fast: false
     steps:
       - name: Dump GitHub context
@@ -80,8 +80,11 @@ jobs:
         if: matrix.pydantic-version == 'pydantic-v1'
         run: uv pip install "pydantic>=1.10.0,<2.0.0"
       - name: Install Pydantic v2
-        if: matrix.pydantic-version == 'pydantic-v2'
-        run: uv pip install --upgrade "pydantic>=2.0.2,<3.0.0"
+        if: matrix.pydantic-version == 'pydantic-v2.7'
+        run: uv pip install --upgrade "pydantic>=2.0.2,<2.8"
+      - name: Install Pydantic v2.8+
+        if: matrix.pydantic-version == 'pydantic-v2.8+'
+        run: uv pip install --upgrade "pydantic>=2.8,<3.0"
       # TODO: Remove this once Python 3.8 is no longer supported
       - name: Install older AnyIO in Python 3.8
         if: matrix.python-version == '3.8'

fastapi/_compat.py

@@ -11,6 +11,7 @@
     FrozenSet,
     List,
     Mapping,
+    Optional,
     Sequence,
     Set,
     Tuple,
@@ -69,8 +70,8 @@
             with_info_plain_validator_function as with_info_plain_validator_function,
         )
     except ImportError:  # pragma: no cover
-        from pydantic_core.core_schema import (
-            general_plain_validator_function as with_info_plain_validator_function,  # noqa: F401
+        from pydantic_core.core_schema import (  # noqa: F401
+            general_plain_validator_function as with_info_plain_validator_function,
         )
 
     RequiredParam = PydanticUndefined
@@ -146,19 +147,35 @@ def serialize(
             exclude_unset: bool = False,
             exclude_defaults: bool = False,
             exclude_none: bool = False,
+            context: Optional[Dict[str, Any]] = None,
         ) -> Any:
             # What calls this code passes a value that already called
             # self._type_adapter.validate_python(value)
-            return self._type_adapter.dump_python(
-                value,
-                mode=mode,
-                include=include,
-                exclude=exclude,
-                by_alias=by_alias,
-                exclude_unset=exclude_unset,
-                exclude_defaults=exclude_defaults,
-                exclude_none=exclude_none,
-            )
+            #
+            # context argument was introduced in pydantic 2.8
+            if PYDANTIC_VERSION >= "2.8":
+                return self._type_adapter.dump_python(
+                    value,
+                    mode=mode,
+                    include=include,
+                    exclude=exclude,
+                    by_alias=by_alias,
+                    exclude_unset=exclude_unset,
+                    exclude_defaults=exclude_defaults,
+                    exclude_none=exclude_none,
+                    context=context,
+                )
+            else:
+                return self._type_adapter.dump_python(
+                    value,
+                    mode=mode,
+                    include=include,
+                    exclude=exclude,
+                    by_alias=by_alias,
+                    exclude_unset=exclude_unset,
+                    exclude_defaults=exclude_defaults,
+                    exclude_none=exclude_none,
+                )
 
         def __hash__(self) -> int:
             # Each ModelField is unique for our purposes, to allow making a dict from

fastapi/applications.py

@@ -1075,6 +1075,7 @@ def add_api_route(
         response_model_exclude_unset: bool = False,
         response_model_exclude_defaults: bool = False,
         response_model_exclude_none: bool = False,
+        response_model_context: Optional[Dict[str, Any]] = None,
         include_in_schema: bool = True,
         response_class: Union[Type[Response], DefaultPlaceholder] = Default(
             JSONResponse
@@ -1105,6 +1106,7 @@ def add_api_route(
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,
@@ -1133,6 +1135,7 @@ def api_route(
         response_model_exclude_unset: bool = False,
         response_model_exclude_defaults: bool = False,
         response_model_exclude_none: bool = False,
+        response_model_context: Optional[Dict[str, Any]] = None,
         include_in_schema: bool = True,
         response_class: Type[Response] = Default(JSONResponse),
         name: Optional[str] = None,
@@ -1162,6 +1165,7 @@ def decorator(func: DecoratedCallable) -> DecoratedCallable:
                 response_model_exclude_unset=response_model_exclude_unset,
                 response_model_exclude_defaults=response_model_exclude_defaults,
                 response_model_exclude_none=response_model_exclude_none,
+                response_model_context=response_model_context,
                 include_in_schema=include_in_schema,
                 response_class=response_class,
                 name=name,
@@ -1711,6 +1715,21 @@ def get(
                 """
             ),
         ] = False,
+        response_model_context: Annotated[
+            Optional[Dict[str, Any]],
+            Doc(
+                """
+                Additional context to pass to Pydantic when creating the response.
+
+                This will be passed in as serialization context to the response model.
+
+                Note: This feature is a noop on pydantic < 2.8
+
+                Read more about serialization context in the
+                [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+                """
+            ),
+        ] = None,
         include_in_schema: Annotated[
             bool,
             Doc(
@@ -1822,6 +1841,7 @@ def read_items():
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,
@@ -2084,6 +2104,21 @@ def put(
                 """
             ),
         ] = False,
+        response_model_context: Annotated[
+            Optional[Dict[str, Any]],
+            Doc(
+                """
+                Additional context to pass to Pydantic when creating the response.
+
+                This will be passed in as serialization context to the response model.
+
+                Note: This feature is a noop on pydantic < 2.8
+
+                Read more about serialization context in the
+                [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+                """
+            ),
+        ] = None,
         include_in_schema: Annotated[
             bool,
             Doc(
@@ -2200,6 +2235,7 @@ def replace_item(item_id: str, item: Item):
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,
@@ -2462,6 +2498,21 @@ def post(
                 """
             ),
         ] = False,
+        response_model_context: Annotated[
+            Optional[Dict[str, Any]],
+            Doc(
+                """
+                Additional context to pass to Pydantic when creating the response.
+
+                This will be passed in as serialization context to the response model.
+
+                Note: This feature is a noop on pydantic < 2.8
+
+                Read more about serialization context in the
+                [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+                """
+            ),
+        ] = None,
         include_in_schema: Annotated[
             bool,
             Doc(
@@ -2578,6 +2629,7 @@ def create_item(item: Item):
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,
@@ -2840,6 +2892,21 @@ def delete(
                 """
             ),
         ] = False,
+        response_model_context: Annotated[
+            Optional[Dict[str, Any]],
+            Doc(
+                """
+                Additional context to pass to Pydantic when creating the response.
+
+                This will be passed in as serialization context to the response model.
+
+                Note: This feature is a noop on pydantic < 2.8
+
+                Read more about serialization context in the
+                [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+                """
+            ),
+        ] = None,
         include_in_schema: Annotated[
             bool,
             Doc(
@@ -2951,6 +3018,7 @@ def delete_item(item_id: str):
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,
@@ -3213,6 +3281,21 @@ def options(
                 """
             ),
         ] = False,
+        response_model_context: Annotated[
+            Optional[Dict[str, Any]],
+            Doc(
+                """
+                Additional context to pass to Pydantic when creating the response.
+
+                This will be passed in as serialization context to the response model.
+
+                Note: This feature is a noop on pydantic < 2.8
+
+                Read more about serialization context in the
+                [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+                """
+            ),
+        ] = None,
         include_in_schema: Annotated[
             bool,
             Doc(
@@ -3324,6 +3407,7 @@ def get_item_options():
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,
@@ -3586,6 +3670,21 @@ def head(
                 """
             ),
         ] = False,
+        response_model_context: Annotated[
+            Optional[Dict[str, Any]],
+            Doc(
+                """
+                Additional context to pass to Pydantic when creating the response.
+
+                This will be passed in as serialization context to the response model.
+
+                Note: This feature is a noop on pydantic < 2.8
+
+                Read more about serialization context in the
+                [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+                """
+            ),
+        ] = None,
         include_in_schema: Annotated[
             bool,
             Doc(
@@ -3697,6 +3796,7 @@ def get_items_headers(response: Response):
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,
@@ -3959,6 +4059,21 @@ def patch(
                 """
             ),
         ] = False,
+        response_model_context: Annotated[
+            Optional[Dict[str, Any]],
+            Doc(
+                """
+                Additional context to pass to Pydantic when creating the response.
+
+                This will be passed in as serialization context to the response model.
+
+                Note: This feature is a noop on pydantic < 2.8
+
+                Read more about serialization context in the
+                [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+                """
+            ),
+        ] = None,
         include_in_schema: Annotated[
             bool,
             Doc(
@@ -4075,6 +4190,7 @@ def update_item(item: Item):
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,
@@ -4337,6 +4453,21 @@ def trace(
                 """
             ),
         ] = False,
+        response_model_context: Annotated[
+            Optional[Dict[str, Any]],
+            Doc(
+                """
+                Additional context to pass to Pydantic when creating the response.
+
+                This will be passed in as serialization context to the response model.
+
+                Note: This feature is a noop on pydantic < 2.8
+
+                Read more about serialization context in the
+                [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/serialization/#serialization-context)
+                """
+            ),
+        ] = None,
         include_in_schema: Annotated[
             bool,
             Doc(
@@ -4448,6 +4579,7 @@ def trace_item(item_id: str):
             response_model_exclude_unset=response_model_exclude_unset,
             response_model_exclude_defaults=response_model_exclude_defaults,
             response_model_exclude_none=response_model_exclude_none,
+            response_model_context=response_model_context,
             include_in_schema=include_in_schema,
             response_class=response_class,
             name=name,