feat: add mypy plugin for partial models

[shivayseth]

Closes the long-standing request for static type-checking support (revisits #2, per the discussion in #78).

What

Adds a mypy plugin, pydantic_partial.mypy, so partials created with model_as_partial() are understood by mypy instead of being seen as the original (still-required) model.

from pydantic import BaseModel
from pydantic_partial import PartialModelMixin

class Foo(PartialModelMixin, BaseModel):
    id: int
    name: str

# no arguments: all fields optional
PartialFoo = Foo.model_as_partial()
reveal_type(PartialFoo())  # PartialFoo, id: int | None, name: str | None
PartialFoo()               # no error

# select fields: only the named ones become optional, the rest stay required
PatchName = Foo.model_as_partial("name")
PatchName(id=1)            # no error (name optional)
PatchName()               # error: missing named argument "id"

Enable alongside Pydantic's own plugin (both required, since this plugin reads the field metadata pydantic.mypy produces):

[tool.mypy]
plugins = ["pydantic.mypy", "pydantic_partial.mypy"]

How

PartialFoo = Foo.model_as_partial() is the Name = call(...) form, which mypy routes through get_dynamic_class_hook, the same mechanism SQLAlchemy uses for Base = declarative_base(). The plugin registers a real TypeInfo at the assignment site (so mypy never has to resolve the call's return value as a type, which is the wall #2 hit), makes the relevant fields Optional, and synthesises a matching __init__. For field-selecting calls it reads each field's has_default from pydantic's metadata so unselected fields keep their real requiredness.

Two details have dedicated regression tests: mypy reports the hook fullname as <module>.<Model>.model_as_partial (not the mixin's), so matching is by method-name suffix plus an MRO check; and pydantic.mypy would generate a required __init__ for the synthetic class, so the plugin's __init__ must win. The hook defer()s until pydantic.mypy has populated its field metadata and rebuilds cleanly on incremental passes.

Scope

Supported: model_as_partial() / as_partial() with no arguments (all fields optional) and with literal field names like model_as_partial("name") (only those become optional), in the Partial = Model.model_as_partial(...) assignment form.

recursive= isn't fully supported yet: the call still produces a flat partial (top-level fields become optional), but nested models aren't recursed into, so it's stricter than the runtime behaviour rather than wrong.

These fall back to mypy's default instead (never a crash or a silently wrong type): field lists that can't be resolved statically (non-literal arguments, *args splats, or dotted names like "items.name"), and non-assignment uses. pyright isn't supported yet.

Notes

I originally planned to split the no-argument and field-selecting cases into two PRs, but since neither leaves anything in a broken state and field selection rounds out the feature, I folded both into this one so it is release-ready as a whole. Happy to split it back out if you would rather review or land them separately.

mypy is added to the dev and tox deps (the plugin imports mypy only when mypy runs). New tests in tests/test_mypy.py run real mypy over fixtures in a subprocess, so a shared .mypy_cache exercises incremental mode. tox, ruff, and pyright all pass.

[ddanier]

Looks very good! Thanks again for putting the effort into this!

I have one question about one of the tests. Besides this I'm completely fine with merging the change and adding the mypy plugin.

I will create a new release when this is merged for sure ;-)

[ddanier]

Nice!

[ddanier]

Very nice you updated the docs! Thanks!

[ddanier]

To be frank I don't know enough about the mypy internals to fully understand this. Still it all looks reasonable and works as expected. So I am very willing to merge it ;-)

[shivayseth]

Thanks a lot for reviewing this!

One heads-up before finalising the next release: I have another completed local commit building on this PR. It adds mypy support for:

• recursive=True;
• dotted selectors such as "items.name" and "items.*";
• nested partials through list, Optional, dict, and tuple wrappers;
• self-referential models;
• creating a partial from an existing partial;
• incremental mypy cache handling;
• graceful fallback for non-literal arguments;
• updated documentation and 11 additional tests.

Because it is a substantial follow-up, I think it would be cleaner to merge #79 after these small review fixes and submit the recursive support as a separate PR immediately afterward. If possible, could we hold the release until you’ve had a chance to review that follow-up too?
Let me know your thoughts!

[ddanier]

Sure, let’s finalize the changes here, then I’ll look at the next PR and decide when to release. I like the idea of having this completely ready 👍