Class basics¶
Instance and class attributes¶
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:
class A:
def __init__(self, x: int) -> None:
self.x = x # 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 comment:
class A:
x = None # type: List[int] # Declare attribute x of type List[int]
a = A()
a.x = [1] # OK
As in Python, a variable defined in the class body can used as a class or an instance variable.
Similarly, you can give explicit types to instance variables defined in a method:
class A:
def __init__(self) -> None:
self.x = [] # type: List[int]
def f(self) -> None:
self.y = 0 # type: Any
You can only define an instance variable within a method if you assign
to it explicitly using self
:
class A:
def __init__(self) -> None:
self.y = 1 # Define y
a = self
a.x = 1 # Error: x not defined
Overriding statically typed methods¶
When overriding a statically typed method, mypy checks that the override has a compatible signature:
class A:
def f(self, x: int) -> None:
...
class B(A):
def f(self, x: str) -> None: # Error: type of x incompatible
...
class C(A):
def f(self, x: int, y: int) -> None: # Error: too many arguments
...
class D(A):
def f(self, x: int) -> None: # OK
...
Note
You can also vary return types covariantly in overriding. For
example, you could override the return type object
with a subtype
such as int
.
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.
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:
class A:
def inc(self, x: int) -> int:
return x + 1
class B(A):
def inc(self, x): # Override, dynamically typed
return 'hello'
b = B()
print(b.inc(1)) # hello
a = b # type: A
print(a.inc(1)) # hello
Abstract base classes and multiple inheritance¶
Mypy uses Python abstract base classes for protocol types. There are
several built-in abstract base classes types (for example,
Sequence
, Iterable
and Iterator
). You can define abstract
base classes using the abc.ABCMeta
metaclass and the
abc.abstractmethod
function decorator.
from abc import ABCMeta, abstractmethod
import typing
class A(metaclass=ABCMeta):
@abstractmethod
def foo(self, x: int) -> None: pass
@abstractmethod
def bar(self) -> str: pass
class B(A):
def foo(self, x: int) -> None: ...
def bar(self) -> str:
return 'x'
a = A() # Error: A is abstract
b = B() # OK
Unlike most Python code, abstract base classes are likely to play a significant role in many complex mypy programs.
A class can inherit any number of classes, both abstract and concrete. As with normal overrides, a dynamically typed method can implement a statically typed abstract method defined in an abstract base class.
Protocols and structural subtyping¶
Note
Structural subtyping is experimental. Some things may not work as expected. Mypy may pass unsafe code or it can reject valid code.
Mypy supports two ways of deciding whether two classes are compatible
as types: nominal subtyping and structural subtyping. Nominal
subtyping is strictly based on the class hierarchy. If class D
inherits class C
, it’s also a subtype of C
. This form of
subtyping is used by default in mypy, since it’s easy to understand
and produces clear and concise error messages, and since it matches
how the native isinstance()
check works – based on class
hierarchy. Structural subtyping can also be useful. Class D
is
a structural subtype of class C
if the former has all attributes
and methods of the latter, and with compatible types.
Structural subtyping can be seen as a static equivalent of duck typing, which is well known to Python programmers. Mypy provides an opt-in support for structural subtyping via protocol classes described below. See PEP 544 for the detailed specification of protocols and structural subtyping in Python.
Simple user-defined protocols¶
You can define a protocol class by inheriting the special
typing_extensions.Protocol
class:
from typing import Iterable
from typing_extensions import Protocol
class SupportsClose(Protocol):
def close(self) -> None:
... # Explicit '...'
class Resource: # No SupportsClose base class!
# ... some methods ...
def close(self) -> None:
self.resource.release()
def close_all(items: Iterable[SupportsClose]) -> None:
for item in items:
item.close()
close_all([Resource(), open('some/file')]) # Okay!
Resource
is a subtype of the SupportClose
protocol since it defines
a compatible close
method. Regular file objects returned by open()
are
similarly compatible with the protocol, as they support close()
.
Note
The Protocol
base class is currently provided in the typing_extensions
package. Once structural subtyping is mature and
PEP 544 has been accepted,
Protocol
will be included in the typing
module. Several library
types such as typing.Sized
and typing.Iterable
will also be changed
into protocols. They are currently treated as regular ABCs by mypy.
Defining subprotocols¶
You can also define subprotocols. Existing protocols can be extended and merged using multiple inheritance. Example:
# ... continuing from the previous example
class SupportsRead(Protocol):
def read(self, amount: int) -> bytes: ...
class TaggedReadableResource(SupportsClose, SupportsRead, Protocol):
label: str
class AdvancedResource(Resource):
def __init__(self, label: str) -> None:
self.label = label
def read(self, amount: int) -> bytes:
# some implementation
...
resource: TaggedReadableResource
resource = AdvancedResource('handle with care') # OK
Note that inheriting from an existing protocol does not automatically
turn the subclass into a protocol – it just creates a regular
(non-protocol) ABC that implements the given protocol (or
protocols). The typing_extensions.Protocol
base class must always
be explicitly present if you are defining a protocol:
class NewProtocol(SupportsClose): # This is NOT a protocol
new_attr: int
class Concrete:
new_attr: int = 0
def close(self) -> None:
...
# Error: nominal subtyping used by default
x: NewProtocol = Concrete() # Error!
Note
You can use Python 3.6 variable annotations (PEP 526) to declare protocol attributes. On Python 2.7 and earlier Python 3 versions you can use type comments and properties.
Recursive protocols¶
Protocols can be recursive (self-referential) and mutually recursive. This is useful for declaring abstract recursive collections such as trees and linked lists:
from typing import TypeVar, Optional
from typing_extensions import Protocol
class TreeLike(Protocol):
value: int
@property
def left(self) -> Optional['TreeLike']: ...
@property
def right(self) -> Optional['TreeLike']: ...
class SimpleTree:
def __init__(self, value: int) -> None:
self.value = value
self.left: Optional['SimpleTree'] = None
self.right: Optional['SimpleTree'] = None
root = SimpleTree(0) # type: TreeLike # OK
Using isinstance()
with protocols¶
You can use a protocol class with isinstance()
if you decorate it
with the typing_extensions.runtime
class decorator. The decorator
adds support for basic runtime structural checks:
from typing_extensions import Protocol, runtime
@runtime
class Portable(Protocol):
handles: int
class Mug:
def __init__(self) -> None:
self.handles = 1
mug = Mug()
if isinstance(mug, Portable):
use(mug.handles) # Works statically and at runtime
Note
isinstance()
with protocols is not completely safe at runtime.
For example, signatures of methods are not checked. The runtime
implementation only checks that all protocol members are defined.