Are type-checker directives in the body of a TypedDict class disallowed?

[bzoracler]

I'd like to simplify some field declarations for use across multiple platforms/python versions etc. like you'd normally do in (non-TypedDict) classes, by issuing directives like sys.version_info, TYPE_CHECKING, etc. in the body of a TypedDict class:

import typing as t
import sys

class A(t.TypedDict):
    if sys.version_info >= (3, 11):
        a: int

I understand the spec as saying that this is disallowed*:

The class body should only contain lines with item definitions of the form key: value_type, optionally preceded by a docstring.

I'm wondering if there's any particular reason for this restriction, or if this is just an oversight in the wording. Currently, the type-checkers behave inconsistently:

• mypy warns if the directive exists and doesn't register fields underneath the directive (mypy Playground);
• pyre fully supports the directives (pyre Playground);
• pyright warns if the directive exists, but supports the directives (pyright Playground);
• pytype doesn't appear to support the directives on any kind of class body (pytype Playground).

---

* However, field docstrings are currently allowed on TypedDict class bodies, even though this doesn't conform to the spec.

from typing import TypedDict

class A(TypedDict):
    a: int
    """An integer"""  # No type-checker complains here

[JelleZijlstra]

I think this should be allowed. Feel free to submit a change to the spec to make this explicit.

This should also apply to NamedTuple bodies.

[erictraut]

Lifting this restriction will be pretty inconvenient in static type checker implementations — at least in pyright, and I presume in mypy as well. The current implementation simply walks the parse tree to identify top-level statements that correspond to field definitions. If we allow conditional statements, a different approach will be needed — one that involves much more costly code flow analysis to detect unreachable code in conditional branches.

Are we sure the need is sufficient to justify a spec change, all of the downstream work associated with changing this in multiple type checkers, and the performance loss that will result?

The alternative is to leave the current restriction in place and require the version checks to be outside the class body.

if sys.version_info >= (3, 11):
    class A(TypedDict):
        a: int
else:
    class A(TypedDict):
        a: str

[bzoracler]

The current implementation simply walks to the parse tree to identify top-level statements that correspond to field definitions.

Based on the playground experiments in the question, pyright seems to understand the directives already (at least, in the case with sys.version_info in TypedDict class bodies); it just provides an additional warning on top. With a Python version of 3.13:

import typing as t
import sys

class A(t.TypedDict):
    if sys.version_info >= (3, 11): a: int  # pyright: TypedDict classes can contain only type annotations
    if sys.version_info >= (3, 14): b: str  # pyright: TypedDict classes can contain only type annotations

a: A = {"a": 1,  # OK
        "b": 1}  # pyright: Type "dict[str, int]" is not assignable to declared type "A" \
                 #          "b" is an undefined item in type "A"

It seems like pyright is already walking through conditional statement bodies (not just top-level statements) and correctly determining whether the fields should exist based on the version information, rather than completely ignoring them like mypy is. Do you expect a heavier performance hit to pyright if this idiom were to be used more commonly?

[sobolevn]

From users' perspective - it is not clear, why if sys.version_info is allowed in regular classes, but not in TypedDicts bodies.

[erictraut]

Looking more closely at the implementation in pyright, fields that are under conditional statements that can be evaluated by the binder (which includes version and platform checks documented in the typing spec) would avoid the need for more costly code flow analysis.

I don't know the implementations of other type checkers well enough to speak to whether it would require a significant change or result in a performance hit.

If we do lift this restriction, the spec will need to be more specific about which statements and forms are allowed and which are not.