Backtestspydanticrun-20261007-130130#13453
RootModel.model_dump() typing signature rejects supported serialization arguments
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
The issue
View on GitHubInitial 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:
contextis restricted todict[str, Any] | Noneinstead ofAny | None.fallbackis missing.polymorphic_serializationis 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.contextwas later widened toAny.fallbackwas subsequently added toBaseModel.model_dump().polymorphic_serializationwas later added toBaseModel.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: b281d5aedThe two patches
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)
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__)