|
| 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