[peewee] add typed fields, queries, and update to some of the new APIs by coleifer · Pull Request #15911 · python/typeshed · GitHub

Attempt to get Peewee's typing a little bit nicer and bring in some of the additions since 4.0.5.

Added:

JSONField + associated methods
Make field access on model class vs model instance work (see note)
Also get Field init params working properly for field-specific kwargs
Add typing to query results
Add typing to a handful of the chainable methods

For field access - peewee uses metaclass magic along with descriptors, kinda like Django. Fields are now generic over their Python value, so Model.field is the field instance for building queries, and instance.field is the value (e.g. str for CharField, related model for a ForeignKeyField, etc). Also specifying null=True makes the instance value optional, which is nice.

Also fix up fn.

Alrighty, I think this one's ready for review any time. Let me know if you have any q's or feedback - I think these changes will massively improve ergonomics for peewee users (all 3 of us lol).

A general comment: Non-obvious Anys need to be documented, i.e. what are the acceptable types and/or why is Any used here. Obvious Anys include dict[str, Any], Callable[..., Any], or Field[Any]. But for example, in _FieldKwargs default: Any and choices: Iterable[tuple[Any, str]] | None need to be explained with a (short) comment, for example:

    default: Any  # Accepted types depend on the field type

(I'm not sure whether that's the correct explanation.)

@srittau - Those should be addressed now in 8413f13. Were there others you were concerned about specifically?

@srittau / team - it really would be fantastic to hear what remaining blockers there are from your side. These changes, I believe, will seriously improve the utility of the stub for Peewee users. Like Django and others, we have a really dynamic API and use metaclass magic and descriptors for field access. These changes address differentiating ModelClass.field vs model_inst.field, something that's historically been a pain point, among a number of other improvements. I hope you will consider merging.

The distribution channel for a second/separate set of stubs is just not there, IMO, so I'm really hoping that these changes can get upstreamed. I can go into more detail about this if you wish, but I think the best value and least pain for existing users is typeshed.

Couple more comments for some Any's that might get flagged.

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

@srittau - I've added a minimal test-case (kinda followed what wtforms is doing, since we have a similar metaclass thing going on). Also commented 3 additional Any's which might be considered non-trivial. I believe this patch is good to go, are you able to review?

Actually, think I'm just gonna start shipping my own stubs, starting w/4.1.1.

Oh, I totally missed this PR, I've send a few other ones for peewee, don't hesitate to grab what I've done if it's good enough for you (it's not much)

@Psycojoker - this is great, many thanks. I'm going to pull in your fixes for chunked, Check, and #15961 (though database can be str or None for deferring init). I've already added one that's doing what #15958 does, except I missed the alias/noop stuff so I'm grabbing that. I don't think the multi types one is probably worth it, since that's internal-only.

Diff is here, coleifer/peewee@32debcb

Thanks!

coleifer and others added 4 commits June 13, 2026 11:20

[peewee] Update to 4.0.8

39ddcb1

[peewee] Type the field classes

ac26f0c

[peewee] Type query results

f1c5d9e

[pre-commit.ci] auto fixes from pre-commit.com hooks

ad32472