Skip to content

Classes

Classes are standard Python classes. Every attribute is declared in the class body or assigned in __init__, and has one type.

What TyPy accepts

Item Rule
Classes with __init__, methods and attributes declared in the body or assigned in __init__ CLS-01
Assigning or calling a name the class does not have is refused CLS-02
A class derived from one class of the program, with its attributes and methods, overriding them CLS-04
Class variables and attribute defaults given a value in the class body CLS-11
@staticmethod, @classmethod, and @property with its setter CLS-06
__eq__, __ne__, __lt__, __le__, __gt__, __ge__ and __hash__ CLS-07
__add__, __radd__ and the other arithmetic, bitwise and unary methods CLS-07
NotImplemented, returned by an operator or comparison method to give way CLS-21
__len__, __getitem__, __setitem__, __delitem__, __contains__ and __bool__ CLS-07
@dataclass, with eq, order, frozen, match_args and field(default=...) CLS-05, CST-06
__str__ and __repr__, used by print, str, repr, f-strings and containers CLS-08
A type object for every type, with object as the root CLS-10
type(x), class and built-in type names as values, __name__ CLS-12

Inside __init__, self is only used to assign and read attributes until every attribute holds a value, so no attribute is ever read empty. A signature that names its own class, or a class defined below it, quotes the name, such as "Node | None".

Instances are equal only to themselves, hashed by identity and true unless their class defines the methods below (CLS-07). A class may derive from an exception class, as Exceptions describes (CLS-03).

Example

class Account:
    owner: str

    def __init__(self, owner: str, balance: int = 0) -> None:
        self.owner = owner
        self.balance = balance
        self.history: list[int] = []

    def deposit(self, amount: int) -> None:
        self.balance += amount
        self.history.append(amount)

    def __repr__(self) -> str:
        return f"Account({self.owner!r}, {self.balance})"


class Node:
    def __init__(self, value: int, next: "Node | None" = None) -> None:
        self.value = value
        self.next = next


account = Account("ada")
account.deposit(50)
chain = Node(1, Node(2))
print(account, account.history, [account], type(account).__name__)
print(chain.value, chain.next is not None, type(chain) is Node)

Inheritance

A class may derive from one class of the program, named by its name or as module.Class (CLS-04). It holds its base's attributes and methods, and its instances may be used wherever the base is expected: as an argument, in a variable, in a list[Base] or as a Base | None.

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

    def describe(self) -> str:
        return "a shape named " + self.name

    def __repr__(self) -> str:
        return f"Shape({self.name!r})"


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


class Label(Shape):
    pass


shapes: list[Shape] = [Square(2), Label("tag")]
for shape in shapes:
    print(shape.describe(), type(shape).__name__, shape)

A subclass may define a method of its base again. A call runs the method of the instance's own class, whatever the type of the variable that holds it, as in CPython:

class Shape:
    def area(self) -> float:
        return 0.0

    def describe(self) -> str:
        return f"area {self.area()}"


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

    def area(self) -> float:
        return self.side * self.side


shapes: list[Shape] = [Shape(), Square(3.0)]
print([shape.describe() for shape in shapes])

An override takes the base method's parameters in the same order and with the same names. Each parameter accepts the type the base's takes, and the result is one the base's result type accepts, as type checkers require; a mismatch is E0404. A parameter with a default in the base has one in the override, which may differ: a call that leaves it out takes the default of the object's class, as in CPython. An override may take or return a type held differently from the base's, such as int | None where the base has int; with a default of its own for such a parameter it is planned for 1.0 (CLS-34). __init__ is not compared, since it runs only on the class being made.

class Shape:
    def area(self) -> float:
        return 0.0


class Label(Shape):
    def area(self) -> str:
        return "none"

A subclass may declare an attribute of its base again only with the same type. The base of a class is object, an exception class or a class of the program defined before it; a built-in type such as int or list is E0201, and several bases are planned for after 1.0.

Calling the base with super()

In a method, super().name(...) calls the method of the nearest base that defines it, and super(Class, self) naming the enclosing class does the same (CLS-14). In __init__, super().__init__(...) runs the base's __init__, which assigns the inherited attributes:

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

    def describe(self) -> str:
        return "shape " + self.name


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

    def describe(self) -> str:
        return super().describe() + f" with side {self.side}"


print(Square(2.0).describe())

When the base's __init__ uses self other than through its attributes, as by calling a method, it may run an override that reads an attribute of the subclass. Such a call of super().__init__(...) comes after the subclass assigns its own attributes, E0309 otherwise, so no attribute is read before it holds a value. super() outside a method is E0414. super(Base, self) names the enclosing class or one of its bases, and the method found is that of the nearest base of Base, as in CPython (CLS-26); with an instance other than self it is planned for 1.0 (CLS-29).

A method may also be called through a class with the instance first, Shape.describe(square), which runs the method that class holds or inherits, not an override, as in CPython. In __init__, Shape.__init__(self, "square") on the instance being built does what super().__init__("square") does, for any base the class derives from, and its attributes count as assigned. A property called through its class is E0401, since CPython's property object cannot be called (CLS-06).

An instance never holds an attribute without a value: calling a class whose body declares an attribute that no __init__ that runs assigns, such as a subclass without __init__ that declares one of its own, is E0309.

class Count(int):
    pass

Testing the class with isinstance

isinstance(value, Class) tests whether a value is an instance of a class or of one derived from it, and a tuple of classes tests each (CLS-09). The classes are named in the call: classes of the program, built-in types such as int or str, and exception classes. Where a test holds, a variable has the tested class's type, so its attributes and methods can be used; the narrowing ends when the variable is assigned (TYP-07):

class Shape:
    pass


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


def radius(shape: Shape | None) -> float:
    if isinstance(shape, Circle):
        return shape.radius
    return 0.0


print(radius(Circle(2.0)), radius(Shape()), radius(None))

A test also narrows after an if whose body cannot fall through, such as if not isinstance(shape, Circle): return, and in the right operand of and. When the checker can tell the answer, as for isinstance(3, int), nothing is tested when the program runs; bool counts as int, as in CPython. A class held in a variable, and issubclass, are planned for 1.0 (CLS-18, CLS-19).

Class variables and defaults

A value in a class body is read as type checkers read it (CLS-11):

Written as Meaning
count = 0 or count: ClassVar[int] = 0 A class variable: one value the class holds, read as Counter.count or self.count
step: int = 1 An attribute with a default: each new instance starts with the class's value, then __init__ may assign it
from typing import ClassVar


class Counter:
    created = 0
    label: ClassVar[str] = "counter"
    step: int = 1

    def __init__(self, start: int) -> None:
        self.value = start
        Counter.created += 1

    def advance(self) -> int:
        self.value += self.step
        return self.value


class Fast(Counter):
    step: int = 5


counter = Counter(0)
fast = Fast(10)
print(counter.advance(), fast.advance(), Counter.created, fast.label)

The class body's values are computed where the class statement runs, as in CPython, and a mutable default is one object that every instance shares. A class variable is assigned through its class, as Counter.created += 1; assigning it through an instance, which gives that one instance a value of its own in CPython, is E0414, and so is assigning a default through the class.

Static methods and properties

@staticmethod makes a function of the class that takes no instance, called as Class.name(...) or through an instance. @property makes a method that is read as an attribute, and @name.setter the method that assigning the attribute calls (CLS-06):

class Temperature:
    def __init__(self, celsius: float) -> None:
        self._celsius = celsius

    @staticmethod
    def from_fahrenheit(fahrenheit: float) -> "Temperature":
        return Temperature((fahrenheit - 32.0) * 5.0 / 9.0)

    @property
    def celsius(self) -> float:
        return self._celsius

    @celsius.setter
    def celsius(self, value: float) -> None:
        if value < -273.15:
            raise ValueError("below absolute zero")
        self._celsius = value


boiling = Temperature.from_fahrenheit(212.0)
boiling.celsius = boiling.celsius - 1.0
print(boiling.celsius)

A subclass may define a property again, and reading it runs the instance's class's getter. A getter takes only self; a setter takes self and a value of the getter's type and returns None. Assigning a property without a setter is E0414, as CPython raises AttributeError for it. A method without self is E0404; decorate it with @staticmethod. A property is assigned through any expression, such as make().name = value or item.name += 1, the value evaluated first, as in CPython. A subclass may redefine a static method, or a method as a static one, and a call through an instance runs the one of the object's class, as in CPython; a call through a class runs that class's (CLS-06).

Class methods

@classmethod makes a method that takes the class it is called through, cls, as CPython does: Square.unit() passes Square, so cls(...) makes a Square. TyPy compiles a copy of the method for each class that has it, and checks cls(...) against that class's __init__ (CLS-06):

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

    @classmethod
    def unit(cls) -> "Shape":
        return cls("unit " + cls.__name__)


class Square(Shape):
    pass


print(Shape.unit().name, Square.unit().name, type(Square.unit()).__name__)

A static method is called through its class, or through any expression that gives the class or one of its instances, which is evaluated first, as in CPython. A class method is called through its class, also a subclass defined in another module, which gets a copy of its own, and through an instance, which passes the instance's class as cls (CLS-25). Through an instance of a generic class it is planned for 1.0 (CLS-30). Assigning a class variable through a subclass that inherits it gives the subclass a variable of its own, as in CPython: the subclass, its subclasses and their instances read it from then on, and the base keeps its own (CLS-25). Assigning it through a variable that holds such a subclass, such as cls in a class method, is planned for 1.0 (CLS-31).

Comparison methods

__eq__, __ne__, __lt__, __le__, __gt__ and __ge__ give a class's instances ==, !=, <, <=, > and >=, and __hash__ their hash (CLS-07). Lists, sets, dicts, in, sorted, min and max call them too, as CPython does:

class Version:
    def __init__(self, major: int, minor: int) -> None:
        self.major = major
        self.minor = minor

    def __eq__(self, other: "Version") -> bool:
        return (self.major, self.minor) == (other.major, other.minor)

    def __lt__(self, other: "Version") -> bool:
        return (self.major, self.minor) < (other.major, other.minor)

    def __hash__(self) -> int:
        return self.major * 1000 + self.minor


versions = [Version(2, 0), Version(1, 5)]
print(Version(1, 5) in versions, sorted(versions)[0].major)
print(len({Version(1, 5), Version(1, 5)}), Version(2, 0) > Version(1, 5))

A comparison method takes self and one value its class's instances are, and returns a bool; __hash__ returns an int. As in CPython, a > b falls back to b.__lt__(a), a != b to not a == b, the right operand's method comes first when its class derives from the left's, and a class that defines __eq__ without __hash__ has no hash, so a set or a dict key of it is E0413. A container compares an instance with an object its __eq__ does not take as unequal.

A comparison or hash method may raise, also when a list, a set, a dict, sorted, min or max calls it: the exception leaves the operation at once, no later method runs, and a set or a dict keeps the items it had, as in CPython. A chain such as low < value < high calls each comparison's method and evaluates value once (CLS-22). sort and sorted call __lt__ with the same items in the same order as CPython 3.15 does; CPython 3.12, 3.13 and 3.14 each call it in another order (OI-27).

Arithmetic methods

__add__, __sub__, __mul__, __truediv__, __floordiv__, __mod__, __pow__, __matmul__, __lshift__, __rshift__, __and__, __or__ and __xor__ give the binary operators, each with its reflected form such as __radd__; __neg__, __pos__ and __invert__ give -x, +x and ~x, and __abs__ gives abs(x) (CLS-07):

class Money:
    def __init__(self, cents: int) -> None:
        self.cents = cents

    def __add__(self, other: "Money") -> "Money":
        return Money(self.cents + other.cents)

    def __rmul__(self, times: int) -> "Money":
        return Money(self.cents * times)


total = Money(250)
total += Money(100)
print(total.cents, (3 * total).cents)

As in CPython, 3 * total falls back to the right operand's __rmul__, and the right operand's reflected method comes first when its class derives from the left's and defines it again. When the reflected method may run, the operator's type joins the two methods' results, such as int | str (CLS-22). x += y calls the class's in-place method, such as __iadd__, when it defines one, and x = x + y otherwise, for any target: an item or an attribute of an expression is evaluated once, as in CPython (CLS-20). An in-place method that only a subclass of the target's class defines is planned for 1.0 (CLS-32).

Giving way with NotImplemented

An operator or comparison method returns NotImplemented when it does not handle the other operand, and the operator then tries the other operand's method, as CPython does (CLS-21):

class Meters:
    def __init__(self, value: float) -> None:
        self.value = value

    def __add__(self, other: "Meters | Feet") -> "Meters":
        if isinstance(other, Meters):
            return Meters(self.value + other.value)
        return NotImplemented

    def __eq__(self, other: "Meters | Feet") -> bool:
        if isinstance(other, Meters):
            return self.value == other.value
        return NotImplemented


class Feet:
    def __init__(self, value: float) -> None:
        self.value = value

    def __radd__(self, other: "Meters | Feet") -> Meters:
        if isinstance(other, Meters):
            return Meters(other.value + self.value * 0.3048)
        return NotImplemented


print((Meters(1.0) + Feet(10.0)).value, Meters(1.0) == Feet(1.0))
print(Meters(2.0) in [Meters(1.0), Meters(2.0)])
try:
    print(Feet(1.0) + Feet(2.0))
except TypeError as error:
    print(error)

When every method gives way, == and != compare identities, and any other operator raises CPython's TypeError. x += y tries the in-place method first, then the methods of x + y. A method that returns NotImplemented gives every method of its name in the classes derived from the same base the return type T | NotImplementedType, so a direct call such as a.__eq__(b) may give NotImplemented, which result is NotImplemented tests. A method that may return both None and NotImplemented is planned for 1.0 (CLS-33), and return NotImplemented in any other function is E0405.

Container methods

__len__ gives len(x), __getitem__, __setitem__ and __delitem__ give x[k], x[k] = v and del x[k], __contains__ gives v in x, and __bool__ gives the truth of if x, not x, bool(x), any and all; without __bool__, an instance is true when __len__ is not zero (CLS-07):

class Shelf:
    def __init__(self) -> None:
        self.books: dict[str, int] = {}

    def __len__(self) -> int:
        return len(self.books)

    def __getitem__(self, title: str) -> int:
        return self.books[title]

    def __setitem__(self, title: str, pages: int) -> None:
        self.books[title] = pages

    def __contains__(self, title: str) -> bool:
        return title in self.books


shelf = Shelf()
shelf["Dune"] = 412
print(len(shelf), shelf["Dune"], "Dune" in shelf, bool(Shelf()))

As in CPython, a negative __len__ raises ValueError, and in on an instance whose class has __iter__ and no __contains__ goes over its items until one is the value or equal to it (CLS-23). A slice such as x[1:2] passes a slice object to __getitem__, __setitem__ or __delitem__, which a parameter annotated slice or int | slice takes, and x[k] += v calls __getitem__, then __setitem__, with x and k evaluated once:

class Row:
    def __init__(self, cells: list[int]) -> None:
        self.cells = cells

    def __getitem__(self, part: slice) -> "Row":
        return Row(self.cells[part])


class Tally:
    def __init__(self) -> None:
        self.counts = [0, 0]

    def __getitem__(self, index: int) -> int:
        return self.counts[index]

    def __setitem__(self, index: int, value: int) -> None:
        self.counts[index] = value


print(Row([1, 2, 3, 4])[1:3].cells)
tally = Tally()
tally[1] += 5
print(tally.counts)

An instance's truth comes from the __bool__ of its own class, or its __len__ when it has no __bool__, also where the variable's type is a base that has neither, or a union, and in any and all (CLS-24). in and for over a class with __getitem__ alone, which CPython reads by position until IndexError, are planned for 1.0 (CST-11).

Dataclasses

@dataclass from dataclasses writes the methods CPython writes for a class: __init__ taking the fields in order, __repr__, and __eq__; with order=True also __lt__, __le__, __gt__ and __ge__, which compare the fields as a tuple; with frozen=True the fields cannot be assigned after __init__; and unless match_args=False, __match_args__, the names of the fields, which class patterns in match read (CLS-05, CST-06, LIB-06):

from dataclasses import dataclass, field


@dataclass(order=True)
class Version:
    major: int
    minor: int = field(default=0)


@dataclass(frozen=True)
class Token:
    kind: str
    text: str


print(sorted([Version(2), Version(1, 5)]), Version(1) == Version(1, 0))
print(Token("name", "x"))

The fields are the annotated names of the class body, after those of a dataclass base, ClassVar ones excepted. As in CPython, a field without a default after one with a default, a mutable default such as [], order=True without eq, a frozen dataclass deriving from a non-frozen one or the reverse, and assigning a field of a frozen instance are errors. A method the class defines itself is kept.

field(default_factory=f) calls f, a class or a function that takes no arguments, for each instance whose __init__ is not given the field (CLS-15). A frozen dataclass, or one given unsafe_hash=True, hashes as the tuple of its fields, so it can be an item of a set or a key of a dict, and one with eq=True that is neither cannot (CLS-16). The options init=False, repr=False, unsafe_hash and slots are taken too (CLS-17):

from dataclasses import dataclass, field


@dataclass(frozen=True)
class Point:
    x: int
    y: int = 0


@dataclass
class Path:
    name: str
    points: list[Point] = field(default_factory=list)


first = Path("a")
first.points.append(Point(1))
print(first, Path("b"), {Point(1, 2), Point(1, 2)})

The other options of field, such as repr or compare, kw_only and weakref_slot are planned for 1.0 (CLS-28).

Attributes are declared

An attribute the class does not declare cannot be added:

class Point:
    def __init__(self) -> None:
        self.x = 0
point = Point()
point.z = 1