Class basics¶

Instance and class attributes¶

The mypy type checker detects if you are trying to access a missing attribute, which is a very common programming error. For this to work correctly, instance and class attributes must be defined or initialized within the class. Mypy infers the types of attributes:

classA:
 def__init__(self, x: int) -> None:
 self.x = x # Aha, attribute 'x' of type 'int'
a = A(1)
a.x = 2 # OK!
a.y = 3 # Error: "A" has no attribute "y"

This is a bit like each class having an implicitly defined __slots__ attribute. This is only enforced during type checking and not when your program is running.

You can declare types of variables in the class body explicitly using a type annotation:

classA:
 x: list[int] # Declare attribute 'x' of type list[int]
a = A()
a.x = [1] # OK

As in Python generally, a variable defined in the class body can be used as a class or an instance variable. (As discussed in the next section, you can override this with a ClassVar annotation.)

Similarly, you can give explicit types to instance variables defined in a method:

classA:
 def__init__(self) -> None:
 self.x: list[int] = []
 deff(self) -> None:
 self.y: Any = 0

You can only define an instance variable within a method if you assign to it explicitly using self:

classA:
 def__init__(self) -> None:
 self.y = 1 # Define 'y'
 a = self
 a.x = 1 # Error: 'x' not defined

Annotating __init__ methods¶

The __init__ method is somewhat special – it doesn’t return a value. This is best expressed as -> None. However, since many feel this is redundant, it is allowed to omit the return type declaration on __init__ methods if at least one argument is annotated. For example, in the following classes __init__ is considered fully annotated:

classC1:
 def__init__(self) -> None:
 self.var = 42
classC2:
 def__init__(self, arg: int):
 self.var = arg

However, if __init__ has no annotated arguments and no return type annotation, it is considered an untyped method:

classC3:
 def__init__(self):
 # This body is not type checked
 self.var = 42 + 'abc'

Class attribute annotations¶

You can use a ClassVar[t] annotation to explicitly declare that a particular attribute should not be set on instances:

fromtypingimport ClassVar
classA:
 x: ClassVar[int] = 0 # Class variable only
A.x += 1 # OK
a = A()
a.x = 1 # Error: Cannot assign to class variable "x" via instance
print(a.x) # OK -- can be read through an instance

It’s not necessary to annotate all class variables using ClassVar. An attribute without the ClassVar annotation can still be used as a class variable. However, mypy won’t prevent it from being used as an instance variable, as discussed previously:

classA:
 x = 0 # Can be used as a class or instance variable
A.x += 1 # OK
a = A()
a.x = 1 # Also OK

Note that ClassVar is not a class, and you can’t use it with isinstance() or issubclass(). It does not change Python runtime behavior – it’s only for type checkers such as mypy (and also helpful for human readers).

You can also omit the square brackets and the variable type in a ClassVar annotation, but this might not do what you’d expect:

classA:
 y: ClassVar = 0 # Type implicitly Any!

In this case the type of the attribute will be implicitly Any. This behavior will change in the future, since it’s surprising.

An explicit ClassVar may be particularly handy to distinguish between class and instance variables with callable types. For example:

fromcollections.abcimport Callable
fromtypingimport ClassVar
classA:
 foo: Callable[[int], None]
 bar: ClassVar[Callable[[A, int], None]]
 bad: Callable[[A], None]
A().foo(42) # OK
A().bar(42) # OK
A().bad() # Error: Too few arguments

Overriding statically typed methods¶

When overriding a statically typed method, mypy checks that the override has a compatible signature:

classBase:
 deff(self, x: int) -> None:
 ...
classDerived1(Base):
 deff(self, x: str) -> None: # Error: type of 'x' incompatible
 ...
classDerived2(Base):
 deff(self, x: int, y: int) -> None: # Error: too many arguments
 ...
classDerived3(Base):
 deff(self, x: int) -> None: # OK
 ...
classDerived4(Base):
 deff(self, x: float) -> None: # OK: mypy treats int as a subtype of float
 ...
classDerived5(Base):
 deff(self, x: int, y: int = 0) -> None: # OK: accepts more than the base
 ... # class method

In order to ensure that your code remains correct when renaming methods, it can be helpful to explicitly mark a method as overriding a base method. This can be done with the @override decorator. @override can be imported from typing starting with Python 3.12 or from typing_extensions for use with older Python versions. If the base method is then renamed while the overriding method is not, mypy will show an error:

fromtypingimport override
classBase:
 deff(self, x: int) -> None:
 ...
 defg_renamed(self, y: str) -> None:
 ...
classDerived1(Base):
 @override
 deff(self, x: int) -> None: # OK
 ...
 @override
 defg(self, y: str) -> None: # Error: no corresponding base method found
 ...

You can also override a statically typed method with a dynamically typed one. This allows dynamically typed code to override methods defined in library classes without worrying about their type signatures.

As always, relying on dynamically typed code can be unsafe. There is no runtime enforcement that the method override returns a value that is compatible with the original return type, since annotations have no effect at runtime:

classBase:
 definc(self, x: int) -> int:
 return x + 1
classDerived(Base):
 definc(self, x): # Override, dynamically typed
 return 'hello' # Incompatible with 'Base', but no mypy error

Abstract base classes and multiple inheritance¶

Mypy supports Python abstract base classes (ABCs). Abstract classes have at least one abstract method or property that must be implemented by any concrete (non-abstract) subclass. You can define abstract base classes using the abc.ABCMeta metaclass and the @abc.abstractmethod function decorator. Example:

fromabcimport ABCMeta, abstractmethod
classAnimal(metaclass=ABCMeta):
 @abstractmethod
 defeat(self, food: str) -> None: pass
 @property
 @abstractmethod
 defcan_walk(self) -> bool: pass
classCat(Animal):
 defeat(self, food: str) -> None:
 ... # Body omitted
 @property
 defcan_walk(self) -> bool:
 return True
x = Animal() # Error: 'Animal' is abstract due to 'eat' and 'can_walk'
y = Cat() # OK

Note that mypy performs checking for unimplemented abstract methods even if you omit the ABCMeta metaclass. This can be useful if the metaclass would cause runtime metaclass conflicts.

Since you can’t create instances of ABCs, they are most commonly used in type annotations. For example, this method accepts arbitrary iterables containing arbitrary animals (instances of concrete Animal subclasses):

deffeed_all(animals: Iterable[Animal], food: str) -> None:
 for animal in animals:
 animal.eat(food)

There is one important peculiarity about how ABCs work in Python – whether a particular class is abstract or not is somewhat implicit. In the example below, Derived is treated as an abstract base class since Derived inherits an abstract f method from Base and doesn’t explicitly implement it. The definition of Derived generates no errors from mypy, since it’s a valid ABC:

fromabcimport ABCMeta, abstractmethod
classBase(metaclass=ABCMeta):
 @abstractmethod
 deff(self, x: int) -> None: pass
classDerived(Base): # No error -- Derived is implicitly abstract
 defg(self) -> None:
 ...

Attempting to create an instance of Derived will be rejected, however:

d = Derived() # Error: 'Derived' is abstract

Mypy allows you to omit the body for an abstract method, but if you do so, it is unsafe to call such method via super(). For example:

fromabcimport abstractmethod
classBase:
 @abstractmethod
 deffoo(self) -> int: pass
 @abstractmethod
 defbar(self) -> int:
 return 0
classSub(Base):
 deffoo(self) -> int:
 return super().foo() + 1 # error: Call to abstract method "foo" of "Base"
 # with trivial body via super() is unsafe
 @abstractmethod
 defbar(self) -> int:
 return super().bar() + 1 # This is OK however.

A class can inherit any number of classes, both abstract and concrete. As with normal overrides, a dynamically typed method can override or implement a statically typed method defined in any base class, including an abstract method defined in an abstract base class.

You can implement an abstract property using either a normal property or an instance variable.

Slots¶

When a class has explicitly defined __slots__, mypy will check that all attributes assigned to are members of __slots__:

classAlbum:
 __slots__ = ('name', 'year')
 def__init__(self, name: str, year: int) -> None:
 self.name = name
 self.year = year
 # Error: Trying to assign name "released" that is not in "__slots__" of type "Album"
 self.released = True
my_album = Album('Songs about Python', 2021)

Mypy will only check attribute assignments against __slots__ when the following conditions hold:

1. All base classes (except builtin ones) must have explicit __slots__ defined (this mirrors Python semantics).

2. __slots__ does not include __dict__. If __slots__ includes __dict__, arbitrary attributes can be set, similar to when __slots__ is not defined (this mirrors Python semantics).

3. All values in __slots__ must be string literals.