Backtestspydanticrun-20261005-183002#13453

Issue #13453 Merged fix PR #13456 Run 5 Oct 2026 · run-20261005-183002 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 B = our agent, Patch A = the merged fix.

Both patches make the same change to the `TYPE_CHECKING`-only `RootModel.model_dump()` declaration. Each one widens `context` to `Any | None`, tightens `include`/`exclude` to `IncEx | None`, and adds `fallback` and `polymorphic_serialization` in the same order as `BaseModel`. Correctness on the reported issue is therefore equivalent.

The difference is in the tests and the surrounding changes.

**Patch B** adds regression cases to `tests/typechecking/root_model.py`, as the issue proposes. Its `assert_type` calls cover `context='prefix'`, `fallback=...` and `polymorphic_serialization=True`. Mypy, Pyright and Pyrefly would reject these before the fix and accept them after. That directly tests the symptom the issue reports, which is static type-checker rejection. B also keeps the `Callable` import inside `TYPE_CHECKING`, which is tidy, and leaves the existing explanatory docstring alone.

**Patch A**'s test is a runtime hack. It sets the global `typing.TYPE_CHECKING = True` and re-executes `root_model.py` as a fresh module. That mutates global interpreter state during the test, and it could break if any `TYPE_CHECKING`-only code in the module, such as the metaclass and `dataclass_transform` tricks, does not run cleanly at runtime. It also never runs a type checker, so it does not confirm the calls actually type-check. The test does catch future signature drift, which has some value. But it also asserts exact docstring equality with `BaseModel.model_dump`, which is brittle.

To satisfy that assertion, Patch A replaces the useful explanatory docstring with a copy of the base docstring. The copied docstring wrongly says `Returns: A dictionary representation of the model` for `RootModel`, whose return value is generally not a dict. It moves the real explanation into a comment. That is churn that adds risk and an inaccuracy.

B is the cleaner, better-targeted fix with the more meaningful tests.

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 47s

Wall-clock time in the container

Full test suite

No new failures

12,265 passed · 501 skipped · 12,766 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

31vs 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+27 −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/typechecking/root_model.pyindex 1149472b..f25dcaac 100644@@ -1,6 +1,8 @@+from typing import Any+ from typing_extensions import assert_type -from pydantic import RootModel+from pydantic import BaseModel, RootModel  IntRootModel = RootModel[int] @@ -17,3 +19,19 @@ class StrRootModel(RootModel[str]): str_root_model = StrRootModel(root='a')  assert_type(str_root_model.root, str)+++# `RootModel.model_dump()` accepts the same arguments as `BaseModel.model_dump()`:+assert_type(str_root_model.model_dump(context='prefix'), Any)+assert_type(RootModel[Any](root=object()).model_dump(mode='json', fallback=lambda _: 'fallback'), Any)+++class Base(BaseModel):+    x: int+++class Sub(Base):+    y: int+++assert_type(RootModel[list[Base]](root=[Sub(x=1, y=2)]).model_dump(polymorphic_serialization=True), 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__)