Backtestspydanticrun-20261007-130130#13453

Issue #13453 Merged fix PR #13456 Run 7 Oct 2026 · run-20261007-130130 pydantic/pydantic

RootModel.model_dump() typing signature rejects supported serialization arguments

Better

Our patch was judged better than the merged fix.

In this judgment, Patch A = our agent, Patch B = the merged fix.

Both patches make the same change to the `TYPE_CHECKING`-only `RootModel.model_dump()` signature: `context: Any | None`, `include`/`exclude` typed as `IncEx | None`, and `fallback` and `polymorphic_serialization` added in the same positions as `BaseModel.model_dump()`. Both fix the root cause equally well, so the decision rests on tests, scope and craft.

Tests: Patch A does what the issue proposes. It adds cases to `tests/typechecking/root_model.py` that pass a string `context`, `fallback` and `polymorphic_serialization`. The Mypy, Pyright and Pyrefly suites would reject these before the fix and accept them after, so they are real regression tests for a typing bug. A's runtime test in `test_root_model.py` would also have passed before the fix, so it adds little, but it does no harm.

Patch B's test re-executes `pydantic/root_model.py` under a fake module name after setting the global `typing.TYPE_CHECKING = True`. It then compares `inspect` signatures and docstrings. This guards against future drift, which is appealing, but the approach is fragile:
- Mutating `typing.TYPE_CHECKING` process-wide can affect any module imported for the first time during that window.
- Re-executing the module creates duplicate class and metaclass objects.
- It ties the test to exact docstring equality, so the test can break for reasons unrelated to the signature.
- It never runs a type checker, which is the actual failure mode in the issue.

Scope and craft: Patch B also rewrites the docstring into a copy of `BaseModel`'s. That copy says `Returns: A dictionary representation of the model`, which is wrong for `RootModel`, whose return is usually the root value. B moves the accurate explanation into a comment. B also moves the `Callable` import out of the `TYPE_CHECKING` block into a runtime import that is only used for annotations, which is inconsistent with the file's conventions. Patch A keeps the import under `TYPE_CHECKING` and leaves the existing docstring alone.

With identical fixes, Patch A has the more appropriate, lower-risk tests and less churn.

The judge saw only the two patches, labelled A and B in random order, with issue links and version numbers removed. The reasoning above is shown verbatim.

Solve

5m 6s

Wall-clock time in the container

Full test suite

No new failures

12,266 passed · 501 skipped · 12,767 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

70vs 84 merged

Changed lines, ours vs merged

Initial Checks

  • I confirm that I'm using Pydantic V2

Description

RootModel inherits the runtime implementation of BaseModel.model_dump(), but defines a separate declaration under TYPE_CHECKING to preserve its more precise return type.

That declaration has diverged from the base method:

  • context is restricted to dict[str, Any] | None instead of Any | None.
  • fallback is missing.
  • polymorphic_serialization is missing.

As a result, Mypy, Pyright, and Pyrefly reject valid calls that succeed at runtime.

All three calls in the example below succeed at runtime.

Mypy currently reports errors equivalent to:

Argument "context" to "model_dump" of "RootModel" has incompatible type "str"
Unexpected keyword argument "fallback" for "model_dump" of "RootModel"
Unexpected keyword argument "polymorphic_serialization" for "model_dump" of "RootModel"

Pyright and Pyrefly report the same signature incompatibilities.

Expected behavior

The type-checking-only RootModel.model_dump() declaration should accept the same parameters, annotations, defaults, and ordering as BaseModel.model_dump(), while preserving the more precise RootModel return annotation.

Cause

The declaration appears to have drifted as the base method evolved:

  • Serialization context originally updated both signatures.
  • BaseModel.context was later widened to Any.
  • fallback was subsequently added to BaseModel.model_dump().
  • polymorphic_serialization was later added to BaseModel.model_dump().

Those later changes were not propagated to the manually maintained RootModel declaration.

Proposed fix

Update only the static RootModel.model_dump() signature and add focused regression cases to tests/typechecking/root_model.py.

No runtime serialization behavior needs to change.

I have prepared and locally validated a focused two-file fix. The following checks pass:

  • Mypy type-checking suite
  • Pyright type-checking suite
  • Pyrefly type-checking suite
  • Focused RootModel serialization tests
  • Ruff lint and formatting checks
  • git diff --check

I would be happy to submit the PR after the issue is reviewed and assigned.

Example Code

from typing import Any

from pydantic import BaseModel, RootModel, SerializationInfo, model_serializer


class ContextRoot(RootModel[str]):
    @model_serializer
    def serialize_root(self, info: SerializationInfo) -> str:
        return f'{info.context}:{self.root}'


class Unknown:
    pass


class Base(BaseModel):
    x: int


class Sub(Base):
    y: int


ContextRoot(root='value').model_dump(context='prefix')

RootModel[Any](root=Unknown()).model_dump(
    mode='json',
    fallback=lambda _: 'fallback',
)

RootModel[list[Base]](root=[Sub(x=1, y=2)]).model_dump(
    polymorphic_serialization=True,
)

Python, Pydantic & OS Version

pydantic version: 2.14.0a1
        pydantic-core version: 2.47.0
          pydantic-core build: profile=debug pgo=false
               python version: 3.13.5 | packaged by Anaconda, Inc. | (main, Jun 12 2025, 11:23:37) [Clang 14.0.6 ]
                     platform: macOS-15.7.3-arm64-arm-64bit-Mach-O
             related packages: mypy-1.18.2 typing_extensions-4.15.0 pydantic-settings-2.7.1 pyright-1.1.407
                       commit: b281d5aed

The two patches

Our patch+66 −4
pydantic/root_model.pyindex d2900433..23ed1bf4 100644@@ -13,8 +13,11 @@ from ._internal import _model_construction, _repr from .main import BaseModel, _object_setattr  if TYPE_CHECKING:+    from collections.abc import Callable+     from .fields import Field as PydanticModelField     from .fields import PrivateAttr as PydanticModelPrivateAttr+    from .main import IncEx      # dataclass_transform could be applied to RootModel directly, but `ModelMetaclass`'s dataclass_transform     # takes priority (at least with pyright). We trick type checkers into thinking we apply dataclass_transform@@ -121,9 +124,9 @@ class RootModel(BaseModel, Generic[RootModelRootType], metaclass=_RootModelMetac             self,             *,             mode: Literal['json', 'python'] | str = 'python',-            include: Any = None,-            exclude: Any = None,-            context: dict[str, Any] | None = None,+            include: IncEx | None = None,+            exclude: IncEx | None = None,+            context: Any | None = None,             by_alias: bool | None = None,             exclude_unset: bool = False,             exclude_defaults: bool = False,@@ -131,7 +134,9 @@ class RootModel(BaseModel, Generic[RootModelRootType], metaclass=_RootModelMetac             exclude_computed_fields: bool = False,             round_trip: bool = False,             warnings: bool | Literal['none', 'warn', 'error'] = True,+            fallback: Callable[[Any], Any] | None = None,             serialize_as_any: bool = False,+            polymorphic_serialization: bool | None = None,         ) -> Any:             """This method is included just to get a more accurate return type for type checkers.             It is included in this `if TYPE_CHECKING:` block since no override is actually necessary.tests/test_root_model.pyindex fa2ca461..fed5169f 100644@@ -15,8 +15,10 @@ from pydantic import (     PydanticDeprecatedSince20,     PydanticUserError,     RootModel,+    SerializationInfo,     ValidationError,     field_serializer,+    model_serializer,     model_validator, ) @@ -721,3 +723,29 @@ def test_model_with_both_docstring_and_field_description() -> None:         'type': 'integer',         'description': 'More detailed description',     }+++def test_model_dump_accepts_base_model_dump_arguments() -> None:+    """`RootModel.model_dump` accepts the same arguments as `BaseModel.model_dump` (non-dict context, `fallback`,+    `polymorphic_serialization`)."""++    class ContextRoot(RootModel[str]):+        @model_serializer+        def serialize_root(self, info: SerializationInfo) -> str:+            return f'{info.context}:{self.root}'++    class Unknown:+        pass++    class Base(BaseModel):+        x: int++    class Sub(Base):+        y: int++    assert ContextRoot(root='value').model_dump(context='prefix') == 'prefix:value'+    assert RootModel[Any](root=Unknown()).model_dump(mode='json', fallback=lambda _: 'fallback') == 'fallback'+    assert RootModel[list[Base]](root=[Sub(x=1, y=2)]).model_dump(polymorphic_serialization=True) == [+        {'x': 1, 'y': 2}+    ]+    assert RootModel[list[Base]](root=[Sub(x=1, y=2)]).model_dump(polymorphic_serialization=False) == [{'x': 1}]tests/typechecking/root_model.pyindex 1149472b..314f585e 100644@@ -1,6 +1,8 @@+from typing import Any+ from typing_extensions import assert_type -from pydantic import RootModel+from pydantic import BaseModel, RootModel, SerializationInfo, model_serializer  IntRootModel = RootModel[int] @@ -17,3 +19,30 @@ class StrRootModel(RootModel[str]): str_root_model = StrRootModel(root='a')  assert_type(str_root_model.root, str)+++class ContextRootModel(RootModel[str]):+    @model_serializer+    def serialize_root(self, info: SerializationInfo) -> str:+        return f'{info.context}:{self.root}'+++class Unknown:+    pass+++class Base(BaseModel):+    x: int+++class Sub(Base):+    y: int+++assert_type(ContextRootModel(root='value').model_dump(context='prefix'), Any)++assert_type(RootModel[Any](root=Unknown()).model_dump(mode='json', fallback=lambda _: 'fallback'), Any)++assert_type(RootModel[list[Base]](root=[Sub(x=1, y=2)]).model_dump(polymorphic_serialization=True), Any)++assert_type(int_root_model.model_dump(include={'root'}, exclude=None), Any) 
Merged fix · PR #13456+71 −13
pydantic/root_model.pyindex d2900433e..4548bd326 100644@@ -2,6 +2,7 @@  from __future__ import annotations as _annotations +from collections.abc import Callable from copy import copy, deepcopy from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar @@ -15,6 +16,7 @@ from .main import BaseModel, _object_setattr if TYPE_CHECKING:     from .fields import Field as PydanticModelField     from .fields import PrivateAttr as PydanticModelPrivateAttr+    from .main import IncEx      # dataclass_transform could be applied to RootModel directly, but `ModelMetaclass`'s dataclass_transform     # takes priority (at least with pyright). We trick type checkers into thinking we apply dataclass_transform@@ -116,14 +118,20 @@ class RootModel(BaseModel, Generic[RootModelRootType], metaclass=_RootModelMetac         return m      if TYPE_CHECKING:+        # This `model_dump()` definition is only provided to get a more accurate return type for type checkers+        # (no override is actually necessary at runtime). Generally, the return type will be `RootModelRootType`,+        # assuming that `RootModelRootType` is not a `BaseModel` subclass. If `RootModelRootType` is a `BaseModel`+        # subclass, then the return type will likely be `dict[str, Any]`, as `model_dump()` calls are recursive.+        # The return type could even be something different, in the case of a custom serializer. Thus, `Any` is+        # used here to catch all of these cases.          def model_dump(  # type: ignore             self,             *,             mode: Literal['json', 'python'] | str = 'python',-            include: Any = None,-            exclude: Any = None,-            context: dict[str, Any] | None = None,+            include: IncEx | None = None,+            exclude: IncEx | None = None,+            context: Any | None = None,             by_alias: bool | None = None,             exclude_unset: bool = False,             exclude_defaults: bool = False,@@ -131,18 +139,39 @@ class RootModel(BaseModel, Generic[RootModelRootType], metaclass=_RootModelMetac             exclude_computed_fields: bool = False,             round_trip: bool = False,             warnings: bool | Literal['none', 'warn', 'error'] = True,+            fallback: Callable[[Any], Any] | None = None,             serialize_as_any: bool = False,+            polymorphic_serialization: bool | None = None,         ) -> Any:-            """This method is included just to get a more accurate return type for type checkers.-            It is included in this `if TYPE_CHECKING:` block since no override is actually necessary.--            See the documentation of `BaseModel.model_dump` for more details about the arguments.--            Generally, this method will have a return type of `RootModelRootType`, assuming that `RootModelRootType` is-            not a `BaseModel` subclass. If `RootModelRootType` is a `BaseModel` subclass, then the return-            type will likely be `dict[str, Any]`, as `model_dump` calls are recursive. The return type could-            even be something different, in the case of a custom serializer.-            Thus, `Any` is used here to catch all of these cases.+            """!!! abstract "Usage Documentation"+                [`model_dump`](../concepts/serialization.md#python-mode)++            Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.++            Args:+                mode: The mode in which `to_python` should run.+                    If mode is 'json', the output will only contain JSON serializable types.+                    If mode is 'python', the output may contain non-JSON-serializable Python objects.+                include: A set of fields to include in the output.+                exclude: A set of fields to exclude from the output.+                context: Additional context to pass to the serializer.+                by_alias: Whether to use the field's alias in the dictionary key if defined.+                exclude_unset: Whether to exclude fields that have not been explicitly set.+                exclude_defaults: Whether to exclude fields that are set to their default value.+                exclude_none: Whether to exclude fields that have a value of `None`.+                exclude_computed_fields: Whether to exclude computed fields.+                    While this can be useful for round-tripping, it is usually recommended to use the dedicated+                    `round_trip` parameter instead.+                round_trip: If True, dumped values should be valid as input for non-idempotent types such as Json[T].+                warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,+                    "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].+                fallback: A function to call when an unknown value is encountered. If not provided,+                    a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError] error is raised.+                serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.+                polymorphic_serialization: Whether to use model and dataclass polymorphic serialization for this call.++            Returns:+                A dictionary representation of the model.             """             ... tests/test_root_model.pyindex fa2ca4612..ce97fca28 100644@@ -1,4 +1,7 @@+import importlib.util+import inspect import pickle+import typing from datetime import date, datetime from typing import Annotated, Any, Generic, Literal, TypeVar @@ -721,3 +724,29 @@ def test_model_with_both_docstring_and_field_description() -> None:         'type': 'integer',         'description': 'More detailed description',     }+++def test_type_checking_model_dump_signature_in_sync_with_base_model() -> None:++    import pydantic.root_model++    spec = importlib.util.spec_from_file_location('pydantic._root_model_type_checking', pydantic.root_model.__file__)+    assert spec is not None and spec.loader is not None+    module = importlib.util.module_from_spec(spec)++    typing.TYPE_CHECKING = True+    try:+        spec.loader.exec_module(module)+    finally:+        typing.TYPE_CHECKING = False++    base_sig = inspect.signature(BaseModel.model_dump)+    root_sig = inspect.signature(module.RootModel.model_dump)++    # The return annotation intentionally differs (`Any` instead of `dict[str, Any]`),+    # but the parameters must match exactly:+    assert list(root_sig.parameters.values()) == list(base_sig.parameters.values())++    assert module.RootModel.model_dump.__doc__ is not None+    assert BaseModel.model_dump.__doc__ is not None+    assert inspect.cleandoc(module.RootModel.model_dump.__doc__) == inspect.cleandoc(BaseModel.model_dump.__doc__)