Typing cheat sheet#
Short, self-contained examples of the rules in Type checking. For how to run the checker and how to handle its errors, see the main page.
Annotations with and without from __future__ import annotations#
On Python versions before 3.14, without the __future__ import, Python
evaluates annotations when the function or class is defined. A name that does
not exist yet at that point, such as the class being defined or a type imported
under if TYPE_CHECKING:, then has to be written as a string. With the import,
annotations are stored as strings automatically, so the quotes are not needed:
class Node:
children: list['Node']
def add_child(self, child: 'Node') -> 'Node':
self.children.append(child)
return child
from __future__ import annotations
class Node:
children: list[Node]
def add_child(self, child: Node) -> Node:
self.children.append(child)
return child
Tools that read annotations at runtime, such as magicgui and Pydantic, need extra care here, as explained in Annotating new code.
Values that may be None#
Write X | None for an optional value and X | Y for a union. They mean the
same as Optional[X] and Union[X, Y], which you will still see in older
modules while napari’s ruff config disables the automatic rewrite (UP007,
UP045).
def format_float(value: float, precision: int | None = None) -> str:
if precision is None:
# since the input `precision` is `None`, set it to a default value
precision = 3
# from here on, the checker knows that `precision` is an `int`
return f'{value:.{precision}f}'
Flexible inputs, concrete outputs#
collections.abc is a Python module establishing abstract, reusable and
pythonic-like interfaces for customizable classes that implement common
patterns.
It’s best to annotate the input types of a function or method through these types. Instead, output types should return clearly defined types. In general the idea is “flexible inputs, strict outputs”.
An abstract type describes what an object can do, not which class it is. Any
class that defines __iter__ counts as an Iterable, without inheriting from
it:
from collections.abc import Iterable
class Fruits:
def __iter__(self):
yield 'apple'
yield 'banana'
isinstance(Fruits(), Iterable) # True
from collections.abc import Iterable, Mapping
def unique_sorted(items: Iterable[str]) -> list[str]:
return sorted(set(items))
def normalize(weights: Mapping[str, float]) -> dict[str, float]:
total = sum(weights.values())
return {name: weight / total for name, weight in weights.items()}
unique_sorted accepts a list, a tuple, a set, a generator, or any custom
object that implements __iter__, such as Fruits above, without changing its
signature. If a function modifies its argument in place, ask for
MutableSequence or MutableMapping instead.
Note
Mapping and Sequence only promise read access, such as lookups, len() and
iteration. MutableMapping and MutableSequence add the methods that change
the object, such as item assignment, append(), pop() and update(). The
collections.abc documentation
lists the methods each type supports.
Generic functions with TypeVar#
When the output type depends on the input type, describe the relationship with
a TypeVar:
from collections.abc import Sequence
from typing import TypeVar
T = TypeVar('T')
def first(items: Sequence[T]) -> T:
return items[0]
The checker now knows that first([1, 2]) is an int and first(["a"]) is a
str. napari still supports Python 3.11, so use TypeVar rather than the
def first[T](...) syntax added in Python 3.12.
NumPy arrays#
import numpy as np
import numpy.typing as npt
def to_float(data: npt.ArrayLike) -> npt.NDArray[np.float64]:
return np.asarray(data, dtype=np.float64)
npt.NDArray is generic in its dtype: np.float64 fills that type parameter,
so npt.NDArray[np.float64] is shorthand for
np.ndarray[tuple[Any, ...], np.dtype[np.float64]], an array of any shape with
a float64 dtype. npt.ArrayLike accepts anything np.asarray can convert,
such as lists, tuples and arrays.
Protocols for “anything with these members”#
A Protocol describes what a function uses instead of which class it expects:
from typing import Protocol
class HasShape(Protocol):
@property
def shape(self) -> tuple[int, ...]: ...
def ndim(data: HasShape) -> int:
return len(data.shape)
Any object with a shape attribute satisfies HasShape without inheriting
from it, so NumPy, dask and zarr arrays all work.
from typing import Protocol
class Named(Protocol):
name: str
def label(self) -> str: ...
class Sample:
name: str
def __init__(self, name: str) -> None:
self.name = name
def label(self) -> str:
return self.name
sample: Named = Sample('cells')
sample.name = 'tissue'
sample.label()
The checker treats name as a read-write attribute, so assigning a str is
allowed and assigning another type is an error. shape on HasShape stays
read-only, so assigning to it is an error. label is a method: the object
must define it, and the checker checks the call and the str return.
Decorate the Protocol with @runtime_checkable only if you also need
isinstance() checks.