Backtestspydanticrun-20261005-183002#13453
RootModel.model_dump() typing signature rejects supported serialization arguments
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
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/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)
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__)