Bug: false `Unexpected keyword argument` in pydantic.mypy plugin (in very specific case)

[tlambert03]

Initial Checks

• I confirm that I'm using Pydantic V2

Description

Summary: In a particular scenario using a base class with ConfigDict(extra="forbid"), recursive models (in my case with tagged unions) can result in a false Unexpected keyword argument mypy error on the subclasses.

Example code

This issue is best explained demonstrated with an actual repo, so I created a mwe repo (which models a simple node graph) here: https://github.com/tlambert03/pydantic-mypy-err

git clone https://github.com/tlambert03/pydantic-mypy-err.git
cd pydantic-mypy-err

pip install mypy==1.14.1 pydantic==2.10.5
mypy example.py

Apologies that this can't be summed up in a simpler example, but hopefully that MWE should immediately demonstrate the problem and allow you to play with some variations.

This file contains the most interesting config, and is reproduced here:

from typing import TYPE_CHECKING, Annotated, ClassVar

from pydantic import BaseModel, ConfigDict, Field

if TYPE_CHECKING:
    from .circle import Circle

    # note, if square were defined after Node in THIS file, mypy is happy.
    from .square import Square


class _MyBase(BaseModel):
    """Base class for all evented pydantic-style models."""

    # Note: without this additional base with extra="forbid" mypy is happy.
    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")


AnyNode = Annotated["Circle | Square", Field(discriminator="node_type")]


class Node(_MyBase):
    name: str | None = Field(default=None, description="Name of the node.")
    parent: AnyNode | None = None

Python, Pydantic & OS Version

pydantic version: 2.10.5
        pydantic-core version: 2.27.2
          pydantic-core build: profile=release pgo=false
                 install path: /Users/talley/Desktop/pydantic-mypy-err/.venv/lib/python3.12/site-packages/pydantic
               python version: 3.12.7 (main, Oct 16 2024, 07:12:08) [Clang 18.1.8 ]
                     platform: macOS-15.2-arm64-arm-64bit
             related packages: mypy-1.14.1 typing_extensions-4.12.2
                       commit: unknown

[Viicos]

Thanks for the clear repro steps, I can reproduce. We don't have capacity to investigate however, so don't expect this to be fixed in the sort time.

Things are also tricky for Pydantic here. I'm assuming you are calling model_rebuild() at some point (because Circle and Square are imported in an if TYPE_CHECKING: block). What I would suggest is:

• if possible, define everything in a single module. This way, the symbols are resolvable.
• set defer_build on all the models where you know the build won't succeed on class definition (because of missing forward references). Later on, once every class is defined, call model_rebuild() on each of them.
• as a general advice, avoid only marking part of an annotation as stringified. This doesn't play at runtime and can introduce caching bugs.

Here is an example of the node.py file:

from typing import Annotated, Literal, ClassVar, TypeAlias

from pydantic import BaseModel, ConfigDict, Field


class _MyBase(BaseModel):
    """Base class for all evented pydantic-style models."""

    # Note: without this additional base with extra="forbid" mypy is happy.
    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")


AnyNode: TypeAlias = 'Annotated[Circle | Square, Field(discriminator="node_type")]'


class Node(_MyBase):
    name: str | None = Field(default=None, description="Name of the node.")
    parent: AnyNode | None = None

    model_config = ConfigDict(defer_build=True)


class Circle(Node):
    node_type: Literal["circle"] = "circle"
    radius: float

    model_config = ConfigDict(defer_build=True)


class Square(Node):
    node_type: Literal["square"] = "square"
    side: float

    model_config = ConfigDict(defer_build=True)


Circle.model_rebuild()
Square.model_rebuild()
Node.model_rebuild()

[tlambert03]

thanks for having a look!

We don't have capacity to investigate however, so don't expect this to be fixed in the sort time.

yes, that's fine. I expected this to be too specific to warrant much attention. Totally get it, just wanted to put my thoughts down somewhere while they were fresh.

Things are also tricky for Pydantic here.

Indeed, the recursive nature of the graph definitely adds to the complexity.

I'm assuming you are calling model_rebuild() at some point

correct, it was here

if possible, define everything in a single module. This way, the symbols are resolvable.

yeah, i also noticed that that would avoid this issue. I will consider that as a fallback 👍. My real use case is of course much more elaborate than the few minimal classes here, so i'd like to avoid this if at all possible.

defer_build

cool. did not know about that. thank you. I think the my issue is also solved if I avoid putting ConfigDict(extra="forbid") on the base class, but instead put it on all subclasses one level lower.

Thanks again for the time you gave to this. If you need to cleanup your issues at any point, i'll understand if you want to close this as not planned. I may eventually look into it myself out of curiosity if I can find the time.

[Viicos]

yeah, i also noticed that that would avoid this issue. I will consider that as a fallback 👍. My real use case is of course much more elaborate than the few minimal classes here, so i'd like to avoid this if at all possible.

You can also keep things in separate modules but still set defer_build, and then call model_rebuild() in a single place.

Crossref:

• Properly rebuild Pydantic models if necessary openapi-generators/openapi-python-client#1176
• Certain recursive type references are not resolved #11250 (comment)

Thanks again for the time you gave to this. If you need to cleanup your issues at any point, i'll understand if you want to close this as not planned. I may eventually look into it myself out of curiosity if I can find the time.

Diving into the mypy internals can be daunting, and it might be that the issue is due to a limitation in the mypy semantic analysis. Might be interesting to see if the same issue happens with stdlib dataclasses (as the mypy plugin follows the same logic).

[tlambert03]

thanks!