Static typing#
The numpy package includes type stubs (.pyi files) for static type-checkers.
The stubs have no effect at runtime. This page covers type inference, annotations, and
shape-typing.
The public typing aliases, which can also be used at runtime, are documented in
numpy.typing, together with the assumptions that the stubs make about the platform and
the type-checker.
This page is specific to NumPy, and isn’t an introduction to static typing in Python. For that, see the Python typing documentation.
Note
reveal_type(x) # T means that static type-checkers infer the type T for
x, see reveal_type.
Introduction#
Static type-checkers use NumPy’s stubs to determine, or infer, the type of each expression, without running the code. This also works for code without annotations:
import numpy as np
x = np.linspace(0, 1, 50)
reveal_type(x) # npt.Array1D[np.float64]
grid = x.reshape(5, 10)
reveal_type(grid) # npt.Array2D[np.float64]
reveal_type(grid.sum(axis=0)) # npt.Array1D[np.float64]
reveal_type(grid > 0.5) # npt.Array2D[np.bool]
reveal_type(grid[0, 0]) # np.float64
Here npt is numpy.typing, and npt.Array1D[np.float64] is the type of a 1-d
array with dtype np.float64. The inferred types describe the number of dimensions
and the dtype of each array, see Shape-typing. npt.Array1D and
npt.Array2D are new in NumPy 2.6. Type-checkers can display an equivalent form, such
as np.ndarray[tuple[int], np.dtype[np.float64]] for npt.Array1D[np.float64].
With these types, type-checkers report mistakes before the code is run:
rows, cols = x.shape # error: x is 1-d, so its shape has 1 value
np.zeros(3, 4) # error: 4 isn't a dtype; a 2-d shape must be a tuple
x[0.5] # error: a float isn't a valid index
len(x.mean()) # error: the mean of x is a scalar
They can also report the use of deprecated functionality:
grid.shape = (10, 5) # deprecated: use reshape instead
np.fix(x) # deprecated: use np.trunc instead
The types of some functions depend on the values of their arguments. For example, for
commonly used subscripts, the number of dimensions of the result of
np.einsum is inferred from the subscripts:
reveal_type(np.einsum("ij,kj->ik", grid, grid)) # npt.Array2D[np.float64]
reveal_type(np.einsum("ij,ij->i", grid, grid)) # npt.Array1D[np.float64]
reveal_type(np.einsum("ij,ij->", grid, grid)) # np.float64
Summary#
The main recommendations of this page are:
Use |
Instead of |
Details |
|---|---|---|
|
|
|
|
|
|
|
|
|
Concrete return types, such as |
|
|
|
|
Type inference#
dtype arguments#
To specify a dtype, pass a NumPy scalar type, such as np.float64, as
the dtype argument. A dtype with a known scalar type, such as the dtype
attribute of an npt.NDArray[np.float64], also works. The following arrays have the
same dtype at runtime, but due to limitations in Python’s type system, only the first
has a known dtype for type-checkers:
import numpy as np
a = np.zeros((2, 3), dtype=np.float64) # yes
reveal_type(a) # npt.Array2D[np.float64]
b = np.eye(3, dtype=float) # no
reveal_type(b) # npt.Array2D[Any]
c = np.zeros(5, dtype="float") # no
reveal_type(c) # npt.Array1D[Any]
d = np.ones((2, 3, 4), dtype="float64") # no
reveal_type(d) # npt.Array3D[Any]
Any is a gradual form, so type-checkers don’t check the dtype of these arrays,
only their number of dimensions in this case. Any is best avoided, because
type-checkers can detect fewer mistakes in code that uses it. Other functions and
methods with a dtype parameter behave the same way, and a scalar result becomes
Any altogether:
import numpy as np
x = np.zeros((2, 3))
reveal_type(x.astype(np.float32)) # npt.Array2D[np.float32]
reveal_type(x.astype("float32")) # npt.Array2D[Any]
reveal_type(x.sum(dtype=np.float32)) # np.float32
reveal_type(x.sum(dtype=float)) # Any
Some commonly used functions also infer the dtype from a few of the other spellings,
but most functions don’t. If the default dtype is what you need, omit the dtype:
import numpy as np
reveal_type(np.linspace(0, 1, 5)) # npt.Array1D[np.float64]
reveal_type(np.eye(3)) # npt.Array2D[np.float64]
reveal_type(np.ones((2, 3, 4))) # npt.Array3D[np.float64]
Shape arguments#
The number of dimensions is inferred from the shape argument, which can be an
int or a tuple of int:
import numpy as np
def f(n: int, shape: tuple[int, ...]) -> None:
reveal_type(np.zeros(n)) # npt.Array1D[np.float64]
reveal_type(np.zeros((n, 3))) # npt.Array2D[np.float64]
# the length of this tuple is not known
reveal_type(np.zeros(shape)) # npt.NDArray[np.float64]
Annotations#
Function annotations#
Annotate the parameter and return types of functions as precisely as possible, and let the type-checker infer the types of local variables. For example, this function fits a straight line through a set of points:
import numpy as np
import numpy.typing as npt
def fit_line(
x: npt.Array1D[np.float64],
y: npt.Array1D[np.float64],
) -> tuple[np.float64, np.float64]:
design = np.column_stack([x, np.ones_like(x)])
reveal_type(design) # npt.Array2D[np.float64]
solution, *_ = np.linalg.lstsq(design, y)
reveal_type(solution) # npt.Array1D[np.float64]
slope, intercept = solution
return slope, intercept
x = np.linspace(0.0, 1.0, 50)
y = 3 * x + 1
slope, intercept = fit_line(x, y)
fit_line(np.column_stack([x, y]), y) # error: 2-d array, expected a 1-d array
Only the signature of fit_line is annotated. The types of design and
solution are inferred. For example, the stubs declare that
np.column_stack returns a 2-d array when it’s given 1-d arrays.
The last call passes a 2-d array as x. At runtime, np.column_stack and
np.linalg.lstsq accept it, and the error only occurs at
slope, intercept = solution, as a ValueError. A static type-checker reports the
error at the call, before the code is run.
Writing npt.Array1D[np.float64] takes no more effort than writing
npt.NDArray[np.float64] or np.ndarray, but only npt.Array1D lets
type-checkers report this error. np.ndarray without type arguments is
equivalent to npt.NDArray[Any]: it has an unknown shape and dtype, and so do most
results that are computed from it:
import numpy as np
import numpy.typing as npt
def f(
untyped: np.ndarray,
floating: npt.NDArray[np.floating],
float64: npt.NDArray[np.float64],
) -> None:
reveal_type(untyped.mean()) # Any
reveal_type(floating.mean()) # np.floating
reveal_type(float64.mean()) # np.float64
Abstract scalar types such as np.floating are useful in parameter
types and as upper bounds of type parameters. Return types should be
concrete, such as np.float64, when possible.
Scalar type promotion#
The dtype of a result often depends on the dtypes of the inputs, following NumPy’s promotion rules, as defined in NEP 50. To describe this in annotations, use type parameters or overloads. If the result has the same dtype as one of the parameters, use a type parameter with an upper bound:
import numpy as np
import numpy.typing as npt
def first_column[ScalarT: np.generic](
a: npt.Array2D[ScalarT],
) -> npt.Array1D[ScalarT]:
return a[:, 0]
Otherwise, use overloads. They are more verbose, but each combination of dtypes can
have its own return type. For example, this midpoint follows the promotion rules for
np.float32 and np.float64:
from typing import overload
import numpy as np
import numpy.typing as npt
@overload
def midpoint(
a: npt.Array1D[np.float32],
b: npt.Array1D[np.float32],
) -> npt.Array1D[np.float32]: ...
@overload
def midpoint(
a: npt.Array1D[np.float32],
b: npt.Array1D[np.float64],
) -> npt.Array1D[np.float64]: ...
@overload
def midpoint(
a: npt.Array1D[np.float64],
b: npt.Array1D[np.float64 | np.float32],
) -> npt.Array1D[np.float64]: ...
def midpoint(
a: npt.Array1D[np.float64 | np.float32],
b: npt.Array1D[np.float64 | np.float32],
) -> npt.Array1D[np.float64 | np.float32]:
return (a + b) / 2
x32 = np.zeros(3, dtype=np.float32)
x64 = np.zeros(3, dtype=np.float64)
reveal_type(midpoint(x32, x32)) # npt.Array1D[np.float32]
reveal_type(midpoint(x32, x64)) # npt.Array1D[np.float64]
reveal_type(midpoint(x64, x32)) # npt.Array1D[np.float64]
A type parameter can’t describe this promotion. If a and b were both annotated
as npt.Array1D[ScalarT], then the dtype of midpoint(x32, x64) wouldn’t be
inferred as np.float64. Depending on the type-checker and the upper bound of
ScalarT, it would be np.float32 | np.float64, or a common supertype such as
np.floating.
ArrayLike and DTypeLike inputs#
Use ArrayLike for parameters that accept array-like objects, and
DTypeLike for parameters that accept dtype-like objects. DTypeLike
doesn’t include None, so write npt.DTypeLike | None for an optional dtype
parameter. Convert array-like inputs with, for example, np.asarray,
which also accepts the dtype:
from typing import Any
import numpy as np
import numpy.typing as npt
def load_table(
values: npt.ArrayLike,
dtype: npt.DTypeLike | None = None,
) -> npt.Array2D[Any]:
table = np.asarray(values, dtype=dtype)
reveal_type(table) # npt.NDArray[Any]
if table.ndim != 2:
raise ValueError("expected a 2-d array")
return table
Type-checkers don’t narrow the type of table based on the ndim check. The
return is accepted because an array with an unknown number of dimensions is
assignable to an array type with any number of dimensions, see
Unknown number of dimensions.
The dtype of table is unknown, because DTypeLike can describe any dtype. With a
fixed dtype, such as np.asarray(values, dtype=np.float64), the type of table
would be npt.NDArray[np.float64]. So use DTypeLike only as a fallback. Where
possible, accept more specific types, such as type[np.float32] and
type[np.float64] in overloads, or type[ScalarT] with a type parameter, so
that type-checkers can infer the dtype of the result.
ArrayLike and DTypeLike exclude some inputs that NumPy accepts at runtime. For
example, ArrayLike excludes generators, which NumPy converts to an object array, and
DTypeLike excludes some dictionaries of fields. See Differences from the runtime NumPy API for
details.
Important
Only use ArrayLike and DTypeLike as parameter types, never as return types.
They are wide unions, for example of Python scalars, nested sequences, strings, and
types, so callers can’t do anything with such a return value without converting or
narrowing it first. Return a concrete type, such as npt.Array2D[np.float64] or
np.dtype[np.float64], instead.
Shape-typing#
np.ndarray is a generic class with two type parameters: the
shape-type, which is the type of np.ndarray.shape, and the dtype
type, which is the type of np.ndarray.dtype. For example, the
shape of an np.ndarray[tuple[int, int], np.dtype[np.float64]] has type
tuple[int, int], and its dtype has type np.dtype[np.float64].
numpy.typing provides type aliases for the common cases. Each alias takes a scalar
type ScalarT as type argument, and is equivalent to
np.ndarray[ShapeT, np.dtype[ScalarT]], with the shape-type ShapeT from this
table:
Alias |
|
Typical use |
|---|---|---|
|
A single value |
|
|
A vector or time series |
|
|
A matrix or table |
|
|
An RGB image |
|
|
A batch of RGB images |
|
|
An unknown number of dimensions |
Added in version 2.6: Array0D, Array1D, Array2D, Array3D, and Array4D.
The shape-type describes the number of dimensions of an array, not the size of each
dimension: Array2D is any 2-d array. See Literal axis sizes for the
reasons.
NDArray[ScalarT] is assignable to each of Array0D[ScalarT],
Array1D[ScalarT], Array2D[ScalarT], Array3D[ScalarT], and
Array4D[ScalarT], and each of these is assignable to NDArray[ScalarT]. Use
NDArray when the number of dimensions isn’t known statically, see
Unknown number of dimensions.
Shape-type propagation#
Type-checkers infer the number of dimensions of the results of indexing, reductions, and reshaping:
import numpy as np
import numpy.typing as npt
def f(a: npt.Array2D[np.float64]) -> None:
reveal_type(a.shape) # tuple[int, int]
rows, cols = a.shape
row = a[0]
reveal_type(row) # npt.Array1D[np.float64]
element = a[0, 0]
reveal_type(element) # np.float64
reveal_type(a.mean()) # np.float64
reveal_type(a.mean(axis=0)) # npt.Array1D[np.float64]
reveal_type(a.ravel()) # npt.Array1D[np.float64]
reveal_type(a.reshape(-1, 2, 2)) # npt.Array3D[np.float64]
rows, cols, depth = a.shape # error: 2 values, expected 3
If the number of dimensions is unknown, the inferred result types are often less precise:
import numpy as np
import numpy.typing as npt
def f(a: npt.NDArray[np.float64]) -> None:
reveal_type(a.shape) # tuple[Any, ...]
row_or_element = a[0]
reveal_type(row_or_element) # Any
reveal_type(a.sum(axis=0, keepdims=True)) # npt.NDArray[np.float64]
# the number of dimensions of these results doesn't depend on the input
reveal_type(a.ravel()) # npt.Array1D[np.float64]
reveal_type(a.reshape(-1, 2)) # npt.Array2D[np.float64]
Shape-typed functions#
A type statement can give a shape-typed array a name:
import numpy as np
import numpy.typing as npt
type ImageRGB = npt.Array3D[np.uint8]
LUMA_WEIGHTS = np.array([0.299, 0.587, 0.114], dtype=np.float32)
def to_grayscale(image: ImageRGB) -> npt.Array2D[np.float32]:
scaled = image.astype(np.float32) / 255
reveal_type(scaled) # npt.Array3D[np.float32]
red_channel = scaled[..., 0]
reveal_type(red_channel) # npt.Array2D[np.float32]
return scaled @ LUMA_WEIGHTS
To preserve the number of dimensions, use a type parameter for the shape-type. Its upper
bound is tuple[int, ...], which every shape-type is assignable to, including
tuple[Any, ...]:
import numpy as np
import numpy.typing as npt
def clip_unit[ShapeT: tuple[int, ...]](
a: np.ndarray[ShapeT, np.dtype[np.float64]],
) -> np.ndarray[ShapeT, np.dtype[np.float64]]:
return a.clip(0.0, 1.0)
def f(a: npt.Array1D[np.float64], b: npt.Array2D[np.float64]) -> None:
reveal_type(clip_unit(a)) # npt.Array1D[np.float64]
reveal_type(clip_unit(b)) # npt.Array2D[np.float64]
Unknown number of dimensions#
The shape-type of NDArray is tuple[Any, ...], which is
assignable to and from tuples of any length. This makes it possible to add
shape-types to existing code one function at a time. However, type-checkers can’t report
errors in the number of dimensions of an NDArray.
Warning
Never use tuple[int, ...] as the shape-type of an array, for example to mean “any
number of dimensions”. Unlike tuple[Any, ...], it is a fully static type, so
it isn’t assignable to fixed-length shape-types such as tuple[int, int]. An array
with this shape-type can’t be passed to functions that expect an Array1D,
Array2D, and so on, which leads to type errors throughout the code. Use
NDArray or tuple[Any, ...] instead.
As the type of a shape value, such as a shape parameter, or as the upper bound of
a shape-type parameter, tuple[int, ...] is fine.
Also avoid Any as the shape-type, as in np.ndarray[Any]. It is more gradual
than tuple[Any, ...], without any advantage: the shape attribute then has
type Any, which is assignable to str and other wrong types.
For example:
from typing import Any
import numpy as np
import numpy.typing as npt
def solve(a: npt.Array2D[np.float64]) -> None: ...
def f(
vector: npt.Array1D[np.float64],
unknown: npt.NDArray[np.float64],
wrong: np.ndarray[tuple[int, ...], np.dtype[np.float64]],
too_gradual: np.ndarray[Any, np.dtype[np.float64]],
) -> None:
solve(unknown)
solve(vector) # error: 1-d array, expected a 2-d array
solve(wrong) # error: not assignable to tuple[int, int]
label: str = too_gradual.shape # accepted, because the shape is Any
Limitations#
Some operations aren’t shape-typed. Operations on arrays with different numbers of
dimensions, such as Array2D - Array1D, usually result in an unknown number of
dimensions, and sometimes in an unknown dtype. The same applies to functions where the
number of dimensions of the result depends on runtime values, such as
np.squeeze.
In these cases, annotate the return type or the variable. keepdims=True can also
help, because it preserves the number of dimensions:
import numpy as np
import numpy.typing as npt
def standardize(a: npt.Array2D[np.float64]) -> npt.Array2D[np.float64]:
mean = a.mean(axis=0, keepdims=True)
std = a.std(axis=0, keepdims=True)
reveal_type(mean) # npt.Array2D[np.float64]
centered = a - mean
reveal_type(centered) # npt.Array2D[np.float64]
return centered / std
Most functions are shape-typed for up to 4 dimensions. Except for operations on arrays
with the same number of dimensions, results with more dimensions usually have an unknown
number of dimensions. There is no Array5D; write
np.ndarray[tuple[int, int, int, int, int], np.dtype[np.float64]] instead.
Shape-types don’t describe the size of each dimension, see Literal axis sizes. Other ways to support exact sizes are being investigated, but there are no concrete plans yet.
Literal axis sizes#
NumPy doesn’t support Literal axis sizes in shape-types, such as
tuple[Literal[2], Literal[3]]. Only int is supported. If you use literal
axis sizes anyway, NumPy can’t guarantee correct type inference.
The reasons are:
Inference: The type system has no arithmetic on literals, and many sizes depend on runtime values. For example,
np.ones(12).reshape((3, -1))has shape(3, 4), but a shape-type taken from the arguments would betuple[Literal[3], Literal[-1]]. Slicing, boolean indexing, concatenation, and broadcasting have the same problem. Only a few functions, such asnp.ones, could infer correct literal sizes, so most results would haveintsizes anyway.Assignability:
intisn’t assignable to aLiteraltype, so most arrays couldn’t be passed to a function that requires literal sizes without acastor a# type: ignorecomment.Stub behavior: The stubs assume that shape-types only describe the number of dimensions. For example, transposing returns the same shape-type, so the transpose of a
(2, 3)array with a literal shape-type would still claim the shape(2, 3)instead of(3, 2).Type-checker differences: Type-checkers handle literals differently, while NumPy aims for the same inference in all of them. Literal shape-types would also make error messages longer.