Examples#

To enable the plugin, one must add it to their mypyconfiguration file:

[mypy]plugins=numpy.typing.mypy_plugin

ArrayLike#

TheArrayLike type tries to avoid creating object arrays. Forexample,

>>>np.array(x**2forxinrange(10))array(<generator object <genexpr> at ...>, dtype=object)

is valid NumPy code which will create a 0-dimensional objectarray. Type checkers will complain about the above example when usingthe NumPy types however. If you really intended to do the above, thenyou can either use a#type:ignore comment:

>>>np.array(x**2forxinrange(10))# type: ignore

or explicitly type the array like object asAny:

>>>fromtypingimportAny>>>array_like:Any=(x**2forxinrange(10))>>>np.array(array_like)array(<generator object <genexpr> at ...>, dtype=object)

ndarray#

It’s possible to mutate the dtype of an array at runtime. For example,the following code is valid:

>>>x=np.array([1,2])>>>x.dtype=np.bool

This sort of mutation is not allowed by the types. Users who want towrite statically typed code should instead use thenumpy.ndarray.viewmethod to create a view of the array with a different dtype.

DTypeLike#

TheDTypeLike type tries to avoid creation of dtype objects usingdictionary of fields like below:

>>>x=np.dtype({"field1":(float,1),"field2":(int,3)})

Although this is valid NumPy code, the type checker will complain about it,since its usage is discouraged.Please see :Data type objects

Number precision#

The precision ofnumpy.number subclasses is treated as a invariant genericparameter (seeNBitBase), simplifying the annotating of processesinvolving precision-based casting.

>>>fromtypingimportTypeVar>>>importnumpyasnp>>>importnumpy.typingasnpt>>>T=TypeVar("T",bound=npt.NBitBase)>>>deffunc(a:np.floating[T],b:np.floating[T])->np.floating[T]:......

Consequently, the likes offloat16,float32 andfloat64 are still sub-types offloating, but, contrary toruntime, they’re not necessarily considered as sub-classes.

fromtypingimportoverloadimportnumpyasnp@overloaddefphase(x:np.complex64)->np.float32:...@overloaddefphase(x:np.complex128)->np.float64:...@overloaddefphase(x:np.clongdouble)->np.longdouble:...defphase(x:np.complexfloating)->np.floating:...

Timedelta64#

Thetimedelta64 class is not considered a subclass ofsignedinteger, the former only inheriting fromgenericwhile static type checking.

0D arrays#

During runtime numpy aggressively casts any passed 0D arrays into theircorrespondinggeneric instance. Until the introduction of shapetyping (seePEP 646) it is unfortunately not possible to make thenecessary distinction between 0D and >0D arrays. While thus not strictlycorrect, all operations that can potentially perform a 0D-array -> scalarcast are currently annotated as exclusively returning anndarray.

If it is known in advance that an operationwill perform a0D-array -> scalar cast, then one can consider manually remedying thesituation with eithertyping.cast or a#type:ignore comment.

Record array dtypes#

The dtype ofnumpy.recarray, and theCreating record arraysfunctions in general, can be specified in one of two ways:

• Directly via thedtype argument.

• With up to five helper arguments that operate vianumpy.rec.format_parser:formats,names,titles,aligned andbyteorder.

These two approaches are currently typed as being mutually exclusive,i.e. ifdtype is specified than one may not specifyformats.While this mutual exclusivity is not (strictly) enforced during runtime,combining both dtype specifiers can lead to unexpected or even downrightbuggy behavior.