Generics¶
A generic function or class takes a type parameter list, as PEP 695
writes it: def first[T](items: list[T]) -> T or class Box[T]:. TyPy
compiles one copy of the function, or of the class, for each set of types
the program uses it with, so a generic call costs what a call written for
those types costs (GEN-01 to GEN-03, ADR-0023, ADR-0028).
What TyPy accepts¶
| Item | Rule |
|---|---|
def name[T, U](...): a generic function at module level |
GEN-01 |
def name[T](self, ...): a method with type parameters, also a static method |
GEN-01 |
class Name(Protocol):, satisfied by any class with its members |
GEN-04 |
class Name[T]:, a generic class, and Name[int] in annotations and calls |
GEN-01 |
class Name[T](Base):, a generic class with a base of the program |
GEN-08 |
class Sub(Name[int]): and class Sub[T](Name[T]):, a class derived from a copy |
GEN-08 |
| A protocol as the type of a variable, an attribute, a result or an item | GEN-10 |
[T: Bound], a bound, and [T: (A, B)], constraints |
GEN-02 |
| One compiled copy for each set of type arguments, with no type at run time | GEN-03 |
| A generic function or class of another module, by name or through the module | GEN-07 |
Generic functions¶
A call gives the type parameters their types from its arguments, as type checkers do. Two arguments that give one parameter different types give it their union:
def first[T](items: list[T]) -> T:
return items[0]
def pair[K, V](key: K, value: V) -> tuple[K, V]:
return (key, value)
def repeat[T](value: T, times: int) -> list[T]:
result: list[T] = []
for _ in range(times):
result.append(value)
return result
print(first([1, 2]), first(["a"]), pair("a", 1), repeat("x", 3))
The body is checked once, before any call, with each type parameter as a
type of its own that offers only what every type offers: it can be
passed, returned, stored, compared with == and printed. A method or an
operator on it is E0412 or E0401, since some type it may stand for has
none:
def twice[T](value: T) -> T:
return value + value
A parameter that no argument gives, such as the T of
def empty[T]() -> list[T], is E0404.
Bounds and constraints¶
A bound, [S: Shape], makes the parameter offer what its bound offers,
and each call checks that its argument is one. Constraints,
[N: (int, float)], make the parameter one of the listed types: the body
is checked once for each, and a call gives the first that takes its
argument:
class Shape:
def area(self) -> float:
return 1.0
class Square(Shape):
def __init__(self, side: float) -> None:
self.side = side
def area(self) -> float:
return self.side * self.side
def largest[S: Shape](shapes: list[S]) -> S:
best = shapes[0]
for shape in shapes:
if shape.area() > best.area():
best = shape
return best
def doubled[N: (int, float)](value: N) -> N:
return value + value
print(largest([Square(1.0), Square(3.0)]).side, doubled(3), doubled(1.5))
A call whose argument is outside the bound or the constraints is E0404.
A function that calls itself with a larger type each time, as
f(x) calling f([x]), would need copies without end; past 64 copies
inside one another it is E0428.
Generic classes¶
A generic class's type parameters type its attributes and methods. A call
takes the types from the arguments of __init__, as a generic function's
call does, or from the class's type arguments, Box[str]("a"). An
annotation names the class with its type arguments, Box[int]; the bare
name is E0408 outside the class's own body:
class Node[T]:
def __init__(self, value: T, next: "Node[T] | None") -> None:
self.value = value
self.next = next
def values(self) -> list[T]:
found: list[T] = [self.value]
rest = self.next
if rest is not None:
found.extend(rest.values())
return found
def first[T](node: Node[T]) -> T:
return node.value
chain = Node(1, Node(2, None))
words = Node[str]("a", None)
print(chain.values(), first(words))
print(type(chain) is Node, isinstance(words, Node))
Each copy, such as Node[int], is a class of its own, which holds an
int in place, and it answers as the generic class: type(chain) is
Node, isinstance(words, Node) holds and __name__ is "Node", as in
CPython. A generic dataclass gets its methods for each copy.
A class variable or a default the class body gives belongs to the
generic class, so every copy shares it, as every instance shares it in
CPython: Counter.made += 1 in Counter[int] and in Counter[str]
counts in one variable. Its annotation may not name a type parameter,
since one value cannot have each copy's type; declare such an attribute
without a value and assign it in __init__.
A static method that names none of the class's type parameters is the
same for every copy and is compiled once. Another static or class
method called through the class takes the types from its arguments,
Box.wrap("a"), or from the class's type arguments, Box[int].make(3);
when neither gives them, the call is E0404.
isinstance(x, Node[int]) is refused, as CPython raises TypeError for
it.
Generic classes with a base¶
A generic class may derive from a class of the program, and every copy
then derives from it: a Box[int] is a Base, takes Base's methods
and may be passed where a Base is expected (GEN-08, ADR-0040):
class Base:
def __init__(self, name: str) -> None:
self.name = name
def describe(self) -> str:
return self.name + " holds " + self.held()
def held(self) -> str:
return "nothing"
class Box[T](Base):
def __init__(self, item: T) -> None:
super().__init__("box")
self.item = item
def held(self) -> str:
return str(self.item)
def show(thing: Base) -> str:
return thing.describe()
print(show(Box(1)), show(Box("a")), isinstance(Box(2.5), Base))
A method that overrides one of the base is checked with the type
parameters as they are: def held(self) -> T would not fit a base
method that returns str, E0404, as type checkers report.
isinstance(x, Box) on a variable whose type is Base keeps that type,
since which copy the object belongs to is known only when the program
runs; narrowing it is planned for 1.0 (GEN-14), and so are the
comparison methods of a generic dataclass derived from a dataclass,
which need it. Pass eq=False to such a dataclass, or derive it from a
class that is not a dataclass.
Classes derived from a generic class¶
A class may derive from a copy of a generic class, which names its type
arguments: class IntBox(Box[int]) holds an int in place and is a
Box[int]. A generic class may derive from a copy for its own type
parameters, class Pair[T](Box[T]), and each of its copies then derives
from the matching copy, Pair[str] from Box[str] (GEN-08, ADR-0040):
class Box[T]:
def __init__(self, item: T) -> None:
self.item = item
def get(self) -> T:
return self.item
class IntBox(Box[int]):
def get(self) -> int:
return super().get() * 10
class Pair[T](Box[T]):
def __init__(self, item: T, other: T) -> None:
super().__init__(item)
self.other = other
def both(self) -> tuple[T, T]:
return (self.get(), self.other)
def read(box: Box[int]) -> int:
return box.get()
print(read(IntBox(3)), read(Pair(1, 2)), Pair("a", "b").both())
print(isinstance(IntBox(1), Box), type(Pair(1, 2)) is Pair)
An override takes the copy's types: def get(self) -> str in IntBox
is E0404, since Box[int].get returns an int. The bare name of a
generic class as a base, class Sub(Box), is E0408, as in annotations.
A class derived from a copy of a generic class that has class methods,
and a dataclass derived from a copy of a generic dataclass, are planned
for 1.0 (GEN-15).
Generic methods¶
A method of a class that is not generic may take type parameters of its
own. A call gives them their types from the arguments after self, as
for a function, and runs the copy for those types:
class Store:
def __init__(self, name: str) -> None:
self.name = name
def pair[T](self, value: T) -> tuple[str, T]:
return (self.name, value)
@staticmethod
def wrap[T](value: T) -> list[T]:
return [value]
store = Store("main")
print(store.pair(1), store.pair("a"), Store.wrap(2.5))
A generic method may override one with as many type parameters, and a call through the base runs the copy of the object's class's method for the same type arguments, as CPython runs the override (GEN-09):
class Visitor:
def visit[T](self, value: T) -> list[T]:
return [value]
class Doubler(Visitor):
def visit[T](self, value: T) -> list[T]:
return super().visit(value) + [value]
def run(visitor: Visitor) -> None:
print(visitor.visit(1), visitor.visit("a"))
run(Visitor())
run(Doubler())
A generic method that overrides a method without type parameters, or one with another number of them, or one in a generic class, is planned for 1.0 (GEN-16).
A method of a generic class may take type parameters of its own. A call
takes the class's from the instance's copy and solves the method's own
from the arguments: Box(1).paired("a") runs the copy of paired for
int and str. A static method that names none of the class's type
parameters is generic over its own alone, so Box.both(1, 2) needs no
type argument of Box (GEN-09).
A class method may take type parameters of its own, and so may one
whose parameter names a protocol: Registry.make("r", 1.5) runs the
copy for a float, and a class derived from Registry gets copies of
its own, as for any class method (GEN-09). It is called through its
class; through an instance it is planned for 1.0 (GEN-16).
Generics of other modules¶
A generic function or class of another module is used as one of the
module's own: imported by name, from tools import first, Box, or
through the module, tools.first([1]) and tools.Box[int]. Its copies
are made from its source and read the names of the module that defines
it, so a copy may call that module's functions, including those whose
names start with an underscore, and read its variables (GEN-07). A type
argument outside a bound or the constraints is reported at the call, in
the module that makes it.
Protocols¶
A protocol lists the methods and attributes a class needs, and any class that has them satisfies it, without naming it. A parameter whose type is a protocol stands for each such class: TyPy compiles the function once for each class it is called with, as if it had a type parameter bounded by the protocol:
from typing import Protocol
class Shape(Protocol):
sides: int
def area(self) -> float: ...
class Square:
def __init__(self, side: float) -> None:
self.side = side
self.sides = 4
def area(self) -> float:
return self.side * self.side
class Triangle:
def __init__(self) -> None:
self.sides = 3
def area(self) -> float:
return 0.5
def describe(shape: Shape) -> str:
return f"{shape.sides} sides, area {shape.area()}"
def total(shapes: list[Shape]) -> float:
return sum([shape.area() for shape in shapes], 0.0)
mixed: list[Square | Triangle] = [Square(2.0), Triangle()]
print(describe(Square(1.0)), describe(Triangle()), total(mixed))
A class satisfies a protocol when it has each method, taking the same
parameters by name with types that accept the protocol's, a default
where the protocol's method has one, and then only parameters with
defaults, and returning a type the protocol's accepts; and each
attribute with the same type. A call with a class that falls short is
E0404, and the message names the member. A protocol's methods are never
run, so their bodies are usually ....
A protocol has no instances: calling it is E0401, and so is
isinstance with a protocol, which raises TypeError in CPython
(GEN-05).
Protocol values¶
A protocol is also the type of a variable, an attribute, a result or a container item. Such a value holds an instance of any class of the program that satisfies the protocol, and a call of one of its methods, or a read of one of its attributes, runs the method or reads the attribute of the object's class, as in CPython (GEN-10, ADR-0041):
from typing import Protocol
class Shape(Protocol):
name: str
def area(self) -> float: ...
class Circle:
def __init__(self, radius: float) -> None:
self.name = "circle"
self.radius = radius
def area(self) -> float:
return 3.0 * self.radius * self.radius
class Square:
def __init__(self, side: float) -> None:
self.name = "square"
self.side = side
def area(self) -> float:
return self.side * self.side
def largest(shapes: list[Shape]) -> Shape:
best = shapes[0]
for shape in shapes:
if shape.area() > best.area():
best = shape
return best
shapes: list[Shape] = [Circle(1.0), Square(2.0)]
print(largest(shapes).name, [shape.area() for shape in shapes])
A parameter of __init__, of another special method or of a property
that names a protocol takes such values too, since the method has one
body. ==, print, len and the other operations a protocol value
meets reach the object's class. A value of a class that lacks a member
of the protocol, or has it with another type, is refused where it would
be held, and the message names the member.
Refused and planned¶
TypeVar and Generic from typing are E0202: a type parameter list
replaces them (GEN-01). A generic type alias, type Pair[T] = tuple[T,
T], is described with the other type aliases.
Type parameters of a special method or a property, of a method that
overrides or is overridden by one with other type parameters, and a
class method with type parameters called through an instance, are
planned for 1.0 (GEN-16). A class that names a protocol as its base,
properties, static methods, class methods, class variables and defaults
of a protocol, a protocol in the signature of its own methods,
assigning an attribute through a protocol value, and a value of a
built-in type held as a protocol are planned for 1.0 (GEN-17). A class
variable or a default whose
annotation names a type parameter of its class (GEN-11), a generic
exception class (GEN-12), a generic protocol (GEN-13), class methods and
dataclass fields inherited through a copy (GEN-15), and *Ts, **P and
defaults of type parameters (GEN-06) are planned for 1.0.