Skip to content

Types and annotations

Every value in a TyPy program has one type, fixed when the program is compiled. Functions are annotated; variables take the type of their first value.

What TyPy accepts

Item Rule
Annotations on every function parameter, except self, and on every return TYP-01
A variable without an annotation takes the type of its first assignment TYP-02
Assigning a value of another type to a variable is refused TYP-03
Inference stays inside one function TYP-04
An empty [], {}, set() or dict() needs an annotation or a typed context TYP-05
list[T], dict[K, V], set[T], tuple[A, B], tuple[T, ...] and T \| None TYP-06
An int is refused where a float is declared, since CPython keeps it an int TYP-09
typing.Any, typing.cast and object annotations are refused TYP-10
A variable read before it is assigned on every path is refused TYP-12
T \| None narrows to T after is not None, a failed is None test or a truth test TYP-13
A variable narrows to a derived class after isinstance TYP-07
A name, class variable or attribute declared Final is not assigned again TYP-08
type Name = annotation at module level names an annotation SMT-10
A \| B, such as int \| str, narrowed by isinstance TYP-14, TYP-07
Iterator[T] and Iterable[T] from typing or collections.abc TYP-15
TracebackType and ModuleType from types CST-10, MOD-10

Iterators and iterables

Iterable[T] takes any built-in iterable of items of type T: a list, a tuple[T, ...] or a tuple whose items all have type T, a set, a dict, whose items are its keys, a view of a dict, a str for T of str, bytes or range for int, and an iterator. The value is the object itself, so a list passed as an iterable can be read twice, as in CPython. Iterator[T] takes an iterator only:

from collections.abc import Iterable, Iterator


def total(values: Iterable[int]) -> int:
    return sum(values) + sum(values)


def countdown(start: int) -> Iterator[int]:
    return iter(range(start, 0, -1))


print(total([1, 2]), total(range(3)), total({4: "x"}), list(countdown(3)))

An iterable may be read by for, iter, a comprehension and the builtins that read an iterable, such as sum and sorted. Its length and its truth depend on which collection it is, so len, bool, not and a condition on it are refused.

The older names of typing spell the types above: Optional[int] is int | None, Union[int, str] is int | str, and List, Dict, Set, Tuple and Type are list, dict, set, tuple and type (LIB-17). Iterable and Iterator, of either module, and List, Dict, Set, Tuple, Type, Optional[...] and Union[...] of typing may also be the class of isinstance and of a class pattern, answered as CPython answers them: a list is Iterable and not an Iterator, its iterator is both, and a class is Iterable when it, or a base, defines __iter__ (TYP-17).

from typing import Optional, Union, List
from collections.abc import Iterable, Iterator


class Bag:
    def __iter__(self) -> Iterator[int]:
        return iter([1, 2])


def describe(value: Optional[Union[int, List[int], Bag]]) -> str:
    if isinstance(value, Optional[int]):
        return "a number or nothing"
    if isinstance(value, Iterable):
        return "something to loop over"
    return "other"


print(describe(None), describe(3), describe([1]), describe(Bag()))

As in CPython, a bare Optional and a subscripted name such as List[int] in isinstance are E0401, and a bare Union is E0202, since CPython 3.12 and 3.13 raise TypeError where 3.14 and 3.15 answer False. The names held in a variable, passed or printed are planned for 1.0 (TYP-18), and so are Sequence, Mapping and the other abstract collections (LIB-20), NamedTuple (CLS-27) and Callable, with function values (FUN-05). typing.Any and typing.cast are refused, since every value in TyPy has one type (TYP-10).

Unions

A | B holds a value of either type, such as int | str, str | bytes, list[int] | dict[str, int] or two classes. A | B and B | A are one type, and a member another member takes is dropped: Circle | Shape is Shape when Circle derives from Shape. A union of objects is held as the object itself; a union with a number, a bool or a tuple among its members is held with a tag that says which member it holds, so storing an int in an int | str allocates nothing (ADR-0027).

A union can be passed, returned, stored in a container, printed, written with str, repr and f-strings, given to type() and tested for truth. A variable that holds a union of fixed tuples, such as tuple[str] | tuple[str, int], is gone over item by item by a loop, a comprehension, list, sorted, sum and the other builtins that read an iterable, each item of the union of the members' item types. Indexed with a literal, such as value[1], it raises IndexError when the tuple it holds is too short, as CPython does; a position outside every member is E0307. isinstance narrows it, in the branch where the test holds and in the branch where it fails. A union of classes that share a base has that base's attributes and methods:

class Shape:
    def __init__(self, name: str) -> None:
        self.name = name


class Circle(Shape):
    def __init__(self, radius: float) -> None:
        super().__init__("circle")
        self.radius = radius


class Square(Shape):
    def __init__(self, side: float) -> None:
        super().__init__("square")
        self.side = side


def size(value: str | list[int]) -> int:
    if isinstance(value, str):
        return len(value)
    return sum(value)


def measure(shape: Circle | Square) -> str:
    if isinstance(shape, Circle):
        return shape.name + " " + str(shape.radius)
    return shape.name + " " + str(shape.side)


print(size("abc"), size([1, 2]), measure(Square(2.0)))

Any other operation on a variable that holds a union, such as a method, an attribute, an operator, an item or len, is checked once for each member, and the program runs the one for the member the object is. Each member must allow it, so an error names the member that does not:

def describe(value: str | bytes) -> str:
    return str(len(value)) + " " + str(value.upper())


def total(values: list[int] | set[int]) -> int:
    return len(values) + sum(values)


print(describe("abc"), describe(b"xy"), total([1, 2]), total({3}))

The results join into one type: value.upper() above is a str | bytes, and value[0] a str | int. A union computed in place, such as value * 2, is used member by member once it is assigned to a variable. Lists, sets and dicts of a union compare, hash and write each item as the member it holds, so 1 and 1.0 are one key, as in CPython. One value assigned to several targets, as in a = items[0] = 1, or unpacked into targets, is held by each target as its own type, a union or an optional among them (TYP-16). A truth test whose member classes test themselves with __len__, or differently from their base, is planned for 0.5 (CLS-24).

Names that keep their value

Final from typing declares a name that its declaration alone assigns. Final[T] gives it the type T, and a bare Final gives it the type of its value. A module or a function declares a Final variable, a class body a Final class variable, and __init__ a Final attribute with self.name: Final = value:

from typing import Final

LIMIT: Final = 10


class Box:
    SIZE: Final[int] = 3

    def __init__(self, width: int) -> None:
        self.width: Final = width


box = Box(LIMIT)
print(Box.SIZE, box.SIZE, box.width)

Any other assignment is E0414, also through global, an augmented assignment, a for target or module.NAME = value. A Final without a value, Final in any other annotation, such as a parameter's, and a Final attribute declared anywhere but the body of __init__ are E0408. CPython runs such a program without a word, since only a type checker reads Final; TyPy refuses it when it compiles the program:

from typing import Final

LIMIT: Final = 10

for step in range(2):
    LIMIT += step

Type aliases

type Name = annotation at module level makes Name stand for the annotation in every annotation of the module. As in CPython, the value is read only when an annotation uses the alias, so it may name a class defined further down, or another alias:

type Score = int
type Scores = list[Score]
type Found = Node | None


class Node:
    def __init__(self, value: Score) -> None:
        self.value = value


def best(scores: Scores) -> Score:
    return max(scores)


def first(nodes: list[Node]) -> Found:
    return nodes[0] if nodes else None


print(best([3, 9]), first([]))

An alias that names itself, such as type Tree = list[Tree], is E0201; a recursive type is planned for after 1.0. An alias defined twice, E0414, and one whose name the module also gives a class, a function or a variable, E0202, are refused, since an annotation would read one meaning of the name.

An alias may take type parameters. Pair[int] stands for the value with int in place of T, and a type parameter of a generic function or class may be the argument:

type Pair[T] = tuple[T, T]
type Table[K, V] = dict[K, list[V]]


def swap[T](pair: Pair[T]) -> Pair[T]:
    return (pair[1], pair[0])


counts: Table[str, int] = {"a": [1, 2]}
print(swap((1, 2)), swap(("x", "y")), counts)

A generic alias named without one type argument for each parameter, such as Pair or Pair[int, int], is E0408. An alias of another module is read as its own module wrote it, imported by name, as in from shapes import Pair, or read through its module, as shapes.Pair[int]. A type statement inside a function, a class or a block makes its alias for the statements after it there. A bound or constraints on an alias's type parameter, as in type Ordered[T: float] = tuple[T, T], are taken as CPython takes them, which checks no argument against them; each use is checked as the type the alias stands for (SMT-12).

Read as a value, an alias of the module's top level, or one imported, is a typing.TypeAliasType, as in CPython: it is written as its name, has __name__ and __module__, and is the same object wherever it is read.

type Score = int
kinds = [Score]
print(Score, Score.__name__, Score.__module__, type(Score), kinds[0] is Score)

As in CPython, calling an alias, or giving it to isinstance, is E0401. An alias a function or a class defines read as a value, whose text CPython 3.14 changed, an alias given its type arguments as a value, and an alias's __value__ and __type_params__ are planned for 1.0 (TYP-18). Two aliases compare with is; == between them is E0407, as for module objects.

Example

def find(names: list[str], wanted: str) -> int | None:
    for index, name in enumerate(names):
        if name == wanted:
            return index
    return None


scores: dict[str, list[float]] = {}
scores["ada"] = [9.5, 8.0]
position = find(["ada", "alan"], "alan")
if position is not None:
    print("found at", position + 1)
print(scores, find([], "x"))

An optional value must be tested before it is used as its base type:

limit: int | None = None
print(limit + 1)