.PY File Format – Type hints

Annotations

Annotations on a function, a class or a module are recorded in its __annotations__. A variable annotation inside a function is neither evaluated nor stored (7.2.2). An annotation with no value binds nothing, so in a class y: int does not create an attribute. Tools such as dataclasses read annotations at run time.

import annotationlib

def f(x: Undefined) -> None:
    pass

annotationlib.get_annotations(f, format=annotationlib.Format.STRING)
# {'x': 'Undefined', 'return': 'None'}

f.__annotations__      # NameError: name 'Undefined' is not defined

Writing types

The aliases typing.List, typing.Dict and similar are deprecated in favour of the built-in forms.

from typing import Protocol, TypedDict, NotRequired

class Sized(Protocol):
    def size(self) -> int: ...

class Movie(TypedDict):
    title: str
    year: NotRequired[int]

def total(items: list[Sized]) -> int:
    return sum(item.size() for item in items)

Generics syntax

Python 3.12 added a syntax for type parameters (PEP 695, Language Reference 8.10): they are written in square brackets after the name.

type_params:  "[" type_param ("," type_param)* "]"
type_param:   typevar | typevartuple | paramspec
typevar:      identifier (":" expression)? ("=" expression)?
typevartuple: "*" identifier ("=" expression)?
paramspec:    "**" identifier ("=" expression)?

def first[T](items: list[T]) -> T:
    return items[0]

class Box[T]:
    def __init__(self, value: T) -> None:
        self.value = value

type Pair[A, B] = tuple[A, B]

def apply[**P, R](fn: Callable[P, R], *args: P.args, **kwargs: P.kwargs) -> R:
    return fn(*args, **kwargs)

• A generic class gets typing.Generic[T] as a base automatically. It can be subscripted, as Box[int].
• Variance is inferred from the class's use of the parameter, so no covariant=True is needed.
• The parameters are visible only inside the definition, through an annotation scope. Bounds, constraints and defaults are lazily evaluated.
• The parameters are stored in __type_params__.
• A class written with the new syntax cannot also list Generic as a base, which raises TypeError. Type checkers also reject an old TypeVar used in such a definition.

Stub files

A stub is a .pyi file holding only type information (PEP 484). Stubs describe modules written in C, and give types to code that has none. Type checkers read the stub instead of the module, and the interpreter never imports it.

import sys
from typing import overload

__all__ = ["read", "parse"]

MAX_SIZE: int

@overload
def read(path: str) -> str: ...
@overload
def read(path: bytes) -> bytes: ...

def parse(text: str, strict: bool = False, depth: int = ...) -> dict[str, object]: ...

class Reader:
    size: int
    def __init__(self, path: str) -> None: ...

if sys.version_info >= (3, 12):
    def extra() -> None: ...

• A stub uses the syntax of a Python module. Function and class bodies are ....
• Simple default values are written out, and ... stands in for anything more complex.
• Forward references need no quotes, since a stub is not run.
• Names that exist only in the stub should start with an underscore. Stubs should not use __future__ imports.
• sys.version_info and sys.platform checks select declarations for a version or platform.
• An imported name is not exported from the stub unless it is written import x as x or from m import x as x, or comes from from m import *.
• __all__ should match the real module.