[1a] Typed model construction via @dataclass_transform

[davegaeddert]

Gives Model(field=…) a per-field typed __init__ — wrong value types, unknown field names, and missing required fields become type errors instead of runtime surprises. Django can't do this (Model(**kwargs) is Any, and django-stubs can't type it per-field), so it's a genuine improvement over the framework Plain forked.

Mechanism

PEP 681 @dataclass_transform on the ModelBase metaclass, listing the types.* constructors as field_specifiers. Purely a type-checker affordance — the runtime __init__ is untouched, and the full suite passes unchanged.

The catch is that PEP 681 only sees annotated class attributes, so this reverses the current "don't annotate fields" rule:

from plain.postgres import Field, types

@postgres.register_model
class Article(postgres.Model):
    title: Field[str] = types.TextField(max_length=100)
    views: Field[int] = types.IntegerField(default=0)
    author: Field[User] = types.ForeignKeyField(User, on_delete=postgres.CASCADE)
    published_at: Field[datetime | None] = types.DateTimeField(allow_null=True, default=None)
    created_at: Field[datetime] = types.DateTimeField(create_now=True)

Access typing is unchanged: Article.title is still Field[str] (the class-level reference the typed query API will build on), article.title is still str.

The one rule to learn

A constructor param is required unless the field has a default= or is DB-owned.

• optional ⟺ the definition passes a call-site default=
• excluded ⟺ DB-owned — id, create_now/update_now, generate=True, RandomStringField — via signature-level init=False overloads in the stubs
• required otherwise

Nullability folds into this with no special case: a nullable field is optional iff it declares default=None, exactly as a string is optional iff it declares default="".

What's in here

• @dataclass_transform on ModelBase, Field exposed publicly as from plain.postgres import Field
• Stub rework: init=False overloads for DB-owned fields; DateTimeField and nullable ForeignKeyField accept default=None
• _ForeignKeyDescriptor subclasses Field[V] so FK annotations check on pyright too, not just ty
• Model.query is a ClassVar — default-queryset models declare nothing and inherit it; only custom-queryset models (cache, jobs) write query: ClassVar[CustomQuerySet]
• Every shipped + example + test-fixture model migrated: 21 model files, 309 annotations, 55 query redeclarations removed
• A conformance test (test_typed_construction_preflight.py) that re-derives the synthesized field set and asserts each entry is a real field — it caught four leak classes during review (model_options/_model_meta, M2M, reverse FK/M2M accessors), two of which a human reviewer missed. Deliberately a test, not a registered preflight: detecting leaks from raw annotations is too fragile to run in every user app's startup.

Known wart

~20 non-nullable required=False fields type as required even though the runtime would supply "". Fixing that narrowly means adding default="", which — because default= currently does double duty as the persistent DB DEFAULT — drags in a redundant 20-column migration driven purely by the type checker. Not worth churning schema for typing; the accurate fix is to decouple those two meanings, which is a separate change.

The imprecision errs in the safe direction: you're asked to provide a value or declare a default, never allowed to omit something that would break.

Migration

All-or-nothing by construction — an unannotated model synthesizes an empty __init__, so a half-migrated model silently gets a wrong constructor. The annotation is mechanically derivable from the field call, so /plain-upgrade can do it; the changelog needs upgrade instructions covering the annotation, the default=None for nullables, dropping query redeclarations, and ClassVar for reverse accessors.

This branch was cut in June and merged forward here. The merge is a useful preview of that all-or-nothing property: plain-oauthserver landed on master afterward, was never annotated, and produced 31 errors on its own until migrated. Two of its call sites needed real adaptation:

• views.py passed user=self.user into a non-null FK, but AuthView.user is User | None and login_required = True doesn't narrow it — a latent hole the untyped constructor hid entirely. Asserted locally; typing login_required views properly is its own change.
• A unit test built partial AuthorizationCode instances to exercise pure methods, which the typed constructor rejects. Needed a helper supplying four required-but-irrelevant values. This is the deliberate tradeoff — the type models the persistence contract while the runtime stays permissive for construct-then-fill — but it's the friction users will feel most.

Review shape

Tiered: the engine (base.py, types.pyi, fields/related.py, the conformance test) carefully; the ~300 mechanical annotations sampled.

Verification

• uv run ty check — clean across the whole repo
• ./scripts/test — 28 suites, 1878 passed, 0 failed
• Checked on both ty 0.0.61 and pyright — same intended catches on both

One gap worth knowing: with @dataclass_transform on, ty performs no assignability check between the annotation and the field, so a wrong Field[T] (title: Field[int] = types.TextField()) passes silently. Pyright catches it. Since the migration is ~300 generated annotations, the upgrade path should either gate on pyright or grow a third conformance check comparing each annotation's T to the field's value type.

[pullapprove5]

PASS: 1 review scope passed

	Scope	Progress
✅	all	0/0

View in PullApprove

Next steps:

• @davegaeddert: Merge or close