Skip to content

Commit 016cb16

Browse files
committed
Add temporary type checker analysis
1 parent bb24c61 commit 016cb16

1 file changed

Lines changed: 356 additions & 0 deletions

File tree

‎metaclass-constructors-checkers.md‎

Lines changed: 356 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,356 @@
1+
# Metaclass constructors: spec examples vs. type checkers
2+
3+
This document runs the examples from the [Metaclass Constructors](docs/spec/constructors.rst)
4+
spec sections against CPython and four type checkers, to assess how far current
5+
implementations are from the proposed behavior.
6+
7+
Environment:
8+
9+
- Runtime: CPython 3.14.5
10+
- mypy 2.3.0 (default settings)
11+
- pyright 1.1.411 (default settings)
12+
- ty 0.0.65 (default settings)
13+
- pyrefly 1.1.1 (`--preset default`; the implicit `basic` preset disables
14+
call-shape validation entirely and reports nothing on these examples)
15+
16+
Each significant line is annotated with a comment of the form:
17+
18+
```
19+
# spec: <expected> | runtime: <ok or exception> | mypy: <ok/error> | pyright: <ok/error> | ty: <ok/error> | pyrefly: <ok/error>
20+
```
21+
22+
- `spec:` is what the spec expects a type checker to report: `error` (should),
23+
`may error` (optional), or `ok` (no error). For `assert_type()` lines, `ok`
24+
means the assertion should pass.
25+
- `runtime:` is what CPython does when the statement is executed. Note that a
26+
line can be a type error while running fine (e.g. a wrongly typed keyword
27+
value is not checked at runtime), and vice versa (an `assert_type()` whose
28+
argument raises).
29+
- A checker column says `error` if the checker reports any diagnostic on that
30+
line, `ok` otherwise.
31+
32+
## Metaclass Constructors (intro example)
33+
34+
```python
35+
from typing import Any, Never, assert_type
36+
37+
38+
class MetaMeta(type):
39+
def __call__(cls, *args, **kwargs) -> Never:
40+
raise TypeError("Classes cannot be created with this metaclass")
41+
42+
43+
class Meta1(type, metaclass=MetaMeta):
44+
pass
45+
46+
47+
# spec: ok | runtime: TypeError (by design) | mypy: error | pyright: ok | ty: ok | pyrefly: ok
48+
assert_type(Meta1("A", (), {}), Never)
49+
50+
51+
class Meta2(type):
52+
def __new__(
53+
mcls,
54+
name: str,
55+
bases: tuple[type, ...],
56+
namespace: dict[str, Any],
57+
*,
58+
key: int,
59+
):
60+
return super().__new__(mcls, name, bases, namespace)
61+
62+
63+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
64+
Meta2("B", (), {}, key=1)
65+
66+
# spec: error | runtime: TypeError | mypy: error | pyright: error | ty: error | pyrefly: error
67+
# runtime: TypeError: Meta2.__new__() missing 1 required keyword-only argument: 'key'
68+
Meta2("B", (), {})
69+
70+
71+
class Meta3(type):
72+
# spec: ok | mypy: error (rejects an int-returning __new__ at the definition) | pyright: ok | ty: ok | pyrefly: ok
73+
def __new__(
74+
mcls, name: str, bases: tuple[type, ...], namespace: dict[str, Any]
75+
) -> int:
76+
return 0
77+
78+
def __init__(cls, x: str) -> None:
79+
pass
80+
81+
82+
# spec: ok | runtime: ok | mypy: error | pyright: ok | ty: ok | pyrefly: ok
83+
assert_type(Meta3("C", (), {}), int)
84+
```
85+
86+
Notes:
87+
88+
- pyright, ty, and pyrefly all honor the metametaclass `__call__()` returning
89+
`Never` and the `__init__()`-skipping rule when `__new__()` returns `int`
90+
(`reveal_type` confirms `Never` and `int` for ty and pyrefly). mypy evaluates
91+
`Meta1(...)` as `Meta1` and rejects the `Meta3.__new__()` definition outright.
92+
- The direct call missing `key` is flagged by **all four** checkers — direct
93+
metaclass calls go through the standard constructor-call rules everywhere.
94+
95+
## The `type` Constructor — single-argument form inference
96+
97+
```python
98+
from typing import assert_type
99+
100+
101+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
102+
def func(x: int, y: int | str) -> None:
103+
assert_type(type(x), type[int])
104+
assert_type(type(y), type[int] | type[str])
105+
```
106+
107+
All four checkers already special-case `type(obj)` to `type[T]`
108+
(pyrefly reveals exactly `type[int]`; ty infers the even more precise class
109+
literal `<class 'int'>` — see next example).
110+
111+
## The `type` Constructor — single-argument form on subclasses
112+
113+
```python
114+
from typing import assert_type
115+
116+
117+
class Meta(type):
118+
pass
119+
120+
121+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: error | pyrefly: ok
122+
assert_type(type(1), type[int])
123+
124+
# spec: error | runtime: TypeError | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
125+
# runtime: TypeError: type.__new__() takes exactly 3 arguments (1 given)
126+
Meta(1)
127+
128+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
129+
Meta("A", (), {})
130+
```
131+
132+
Notes:
133+
134+
- **No checker currently reports `Meta(1)`**: all four inherit the
135+
single-argument overload of `type.__new__()`/`type.__init__()` into the
136+
subclass.
137+
- ty's error on `assert_type(type(1), type[int])` is an artifact of it inferring
138+
the *more precise* class literal `<class 'int'>` for `type(1)` and reporting
139+
the mismatch as `assert-type-unspellable-subtype`; the inference itself is
140+
compliant.
141+
142+
## Class Statements — keyword arguments vs. the metaclass constructor
143+
144+
```python
145+
from typing import Any
146+
147+
148+
class Meta(type):
149+
def __new__(
150+
mcls,
151+
name: str,
152+
bases: tuple[type, ...],
153+
namespace: dict[str, Any],
154+
*,
155+
key: int,
156+
):
157+
return super().__new__(mcls, name, bases, namespace)
158+
159+
160+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
161+
class MyClass1(metaclass=Meta, key=3):
162+
pass
163+
164+
165+
# spec: error (wrong type for "key") | runtime: ok | mypy: ok | pyright: error | ty: ok | pyrefly: ok
166+
class MyClass2(metaclass=Meta, key=""):
167+
pass
168+
169+
170+
# spec: error (missing "key") | runtime: TypeError | mypy: ok | pyright: error | ty: ok | pyrefly: ok
171+
# runtime: TypeError: Meta.__new__() missing 1 required keyword-only argument: 'key'
172+
class MyClass3(metaclass=Meta):
173+
pass
174+
175+
176+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
177+
Meta("MyClass4", (), {}, key=3)
178+
179+
# spec: error (wrong type for "key") | runtime: ok | mypy: error | pyright: error | ty: error | pyrefly: error
180+
Meta("MyClass5", (), {}, key="")
181+
```
182+
183+
Notes:
184+
185+
- Only pyright validates class-statement keyword arguments against a custom
186+
metaclass `__new__()` today. mypy, ty, and pyrefly all miss `MyClass2` and
187+
`MyClass3` — including the missing-argument case that fails at runtime.
188+
- The equivalent *direct* calls are validated by all four checkers through the
189+
standard constructor-call rules.
190+
191+
## Class Statements — the implied `__prepare__` call
192+
193+
```python
194+
from typing import Any
195+
196+
197+
class Meta(type):
198+
# all four checkers report an override-incompatibility error at this
199+
# definition (parameter "**kwds" missing vs. type.__prepare__); that check
200+
# is unrelated to validating the implied __prepare__ call below
201+
@classmethod
202+
def __prepare__(mcls, name: str, bases: tuple[type, ...]): # No **kwds
203+
return {}
204+
205+
def __new__(
206+
mcls,
207+
name: str,
208+
bases: tuple[type, ...],
209+
namespace: dict[str, Any],
210+
*,
211+
key: int,
212+
):
213+
return super().__new__(mcls, name, bases, namespace)
214+
215+
216+
# spec: may error | runtime: TypeError | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
217+
# runtime: TypeError: Meta.__prepare__() got an unexpected keyword argument 'key'
218+
class MyClass6(metaclass=Meta, key=3):
219+
pass
220+
```
221+
222+
No checker validates the implied `__prepare__` call at the class statement
223+
(consistent with the spec's "may"). All four do flag the `__prepare__`
224+
*definition* as an incompatible override of `type.__prepare__()`, which
225+
indirectly catches this class of bug.
226+
227+
## The `__init_subclass__()` Method — no custom metaclass `__new__()`
228+
229+
```python
230+
class Base:
231+
def __init_subclass__(cls, *, flag: bool = False) -> None:
232+
super().__init_subclass__()
233+
234+
235+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
236+
class MyClass1(Base, flag=True):
237+
pass
238+
239+
240+
# spec: error (wrong type for "flag") | runtime: ok | mypy: error | pyright: error | ty: error | pyrefly: ok
241+
class MyClass2(Base, flag=""):
242+
pass
243+
244+
245+
# spec: error (unknown argument) | runtime: TypeError | mypy: error | pyright: error | ty: error | pyrefly: ok
246+
# runtime: TypeError: Base.__init_subclass__() got an unexpected keyword argument 'other'
247+
class MyClass3(Base, other=1):
248+
pass
249+
250+
251+
# spec: error (object.__init_subclass__ accepts no kwargs) | runtime: TypeError | mypy: error | pyright: error | ty: ok | pyrefly: ok
252+
# runtime: TypeError: MyClass4.__init_subclass__() takes no keyword arguments
253+
class MyClass4(other=1):
254+
pass
255+
```
256+
257+
mypy, pyright, and ty implement this rule (ty misses only the
258+
`object.__init_subclass__()` case); pyrefly performs no class-keyword validation.
259+
260+
## The `__init_subclass__()` Method — metaclass with only a custom `__init__()`
261+
262+
```python
263+
from typing import Any
264+
265+
266+
class Base:
267+
def __init_subclass__(cls, *, flag: bool = False) -> None:
268+
super().__init_subclass__()
269+
270+
271+
class MetaInit(type):
272+
def __init__(
273+
cls,
274+
name: str,
275+
bases: tuple[type, ...],
276+
namespace: dict[str, Any],
277+
*,
278+
key: int,
279+
) -> None:
280+
super().__init__(name, bases, namespace)
281+
282+
283+
# spec: error | runtime: TypeError | mypy: ok | pyright: error | ty: error | pyrefly: ok
284+
# runtime: TypeError: Base.__init_subclass__() got an unexpected keyword argument 'key'
285+
class MyClass5(Base, metaclass=MetaInit, key=1):
286+
pass
287+
```
288+
289+
`key` is accepted by `MetaInit.__init__()`, but `type.__new__()` (not
290+
overridden) still forwards it to `Base.__init_subclass__()`, which rejects it.
291+
pyright and ty report it; mypy and pyrefly do not.
292+
293+
## The `__init_subclass__()` Method — forwarding through direct calls and `**kwargs`
294+
295+
```python
296+
from typing import Any
297+
298+
299+
class Base:
300+
def __init_subclass__(cls, *, flag: bool = False) -> None:
301+
super().__init_subclass__()
302+
303+
304+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
305+
type("D", (Base,), {}, flag=True)
306+
307+
# spec: may error | runtime: TypeError | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
308+
# runtime: TypeError: Base.__init_subclass__() got an unexpected keyword argument 'other'
309+
type("E", (Base,), {}, other=1)
310+
311+
312+
class MetaKwargs(type):
313+
def __new__(
314+
mcls,
315+
name: str,
316+
bases: tuple[type, ...],
317+
namespace: dict[str, Any],
318+
**kwargs: Any,
319+
):
320+
return super().__new__(mcls, name, bases, namespace, **kwargs)
321+
322+
323+
# spec: ok | runtime: ok | mypy: ok | pyright: ok | ty: ok | pyrefly: ok
324+
class MyClass7(Base, metaclass=MetaKwargs, flag=True):
325+
pass
326+
327+
328+
# spec: may error | runtime: TypeError | mypy: ok | pyright: ok | ty: error | pyrefly: ok
329+
# runtime: TypeError: Base.__init_subclass__() got an unexpected keyword argument 'other'
330+
class MyClass8(Base, metaclass=MetaKwargs, other=1):
331+
pass
332+
```
333+
334+
No checker validates `__init_subclass__()` through a *direct* `type(...)` call.
335+
Only ty follows the forwarding through a `**kwargs`-accepting metaclass
336+
`__new__()` in a class statement, a consequence of ty checking
337+
`__init_subclass__()` unconditionally — which also produces false positives
338+
when a strict metaclass *consumes* a keyword argument (e.g.
339+
`class C(Base, metaclass=MetaStrict, key=1)` where `key` never reaches
340+
`__init_subclass__()`).
341+
342+
## Summary of divergences from the proposed spec text
343+
344+
| Rule | mypy | pyright | ty | pyrefly |
345+
| --- | --- | --- | --- | --- |
346+
| `type(obj)` evaluates to `type[T]` | yes | yes | yes (more precise) | yes |
347+
| One-argument form rejected on `type` subclasses | no | no | no | no |
348+
| Metametaclass `__call__()` governs metaclass calls | no | yes | yes | yes |
349+
| `__init__()` skipped when metaclass `__new__()` returns non-instance | no | yes | yes | yes |
350+
| Direct metaclass call arguments validated | yes | yes | yes | yes |
351+
| Class-statement kwargs vs. custom metaclass `__new__()` | no | yes | no | no |
352+
| Class-statement kwargs vs. `__init_subclass__()` (should) | yes | yes | mostly | no |
353+
| `__init__()`-only metaclass still checks `__init_subclass__()` | no | yes | yes | no |
354+
| `__prepare__()` implied call (may) | no | no | no | no |
355+
| Direct-call `__init_subclass__()` forwarding (may) | no | no | no | no |
356+
| `**kwargs` metaclass forwarding (may) | no | no | yes | no |

0 commit comments

Comments
 (0)