Thanks to @erictraut’s work, instance constructors are specified in this chapter. I’d like to extend this chapter for metaclass constructors. Thankfully, it mostly follows the same rules, but needs some extra information regarding class keyword arguments and how they interact with __prepare__ and __init_subclass__(), as well as special casing type().
The update to the chapter can be reviewed on this PR:
and a preview is available here: Constructors — typing documentation.
Also included in the PR is a Markdown document showing the current behavior across mypy, pyrefly, pyright and ty (as well as the spec’d and runtime behavior).
I left a couple comments on the PR, and I’m also not too sure which parts of the spec must vs should be supported by type checkers. I’d like to defer on type checker authors, who will be able to better judge the complexity of some of the specified behaviors.
Disclaimer: I used AI to draft a first version of the document, by giving it access to the data model reference, PEP 487, PEP 3115 and parts of the Python documentation. The draft got heavily updated after review.