numpydantic

Top-level API contents

class NDArray(val: NDArrayType)[source]

Constrained array type allowing npytyping syntax for dtype and shape validation and serialization.

This class is not intended to be instantiable, and support for static type checking is limited, it implements the __get_pydantic_core_schema__ method to invoke the relevant interface for validation and serialization.

It is callable, however, which validates and attempts to coerce input to a supported array type. There is no such thing as an “NDArray instance,” but one can think of it as a validating passthrough callable.

References

NDArraySchema(shape: type[~numpydantic.validation.shape.Shape[*, ...]] | ~numpydantic.validation.shape.Shape[*, ...] | str | tuple = Shape['*, ...'], dtype: str | type | ~typing.Any | ~numpy.generic = typing.Any) → GetPydanticSchema[source]

Specify shape and dtype constraints in an typing.Annotated type.

In addition to validating dtype and shape constraints, the type of the array will also be validated - i.e. if the annotation is for a numpy.ndarray, a dask.array.Array will be rejected even if it has the correct shape and dtype.

Examples

>>> from typing import Annotated as A
>>> from numpydantic import Shape, NDArraySchema
>>> import numpy as np
>>> from pydantic import BaseModel

>>> class MyModel(BaseModel):
>>>     array: A[np.ndarray, NDArraySchema(Shape(3, 3), np.uint8)]

or, without Shape

>>> class MyOtherModel(BaseModel):
>>>     array: A[np.ndarray, NDArraySchema((3, 3), np.uint8)]

Valid:

>>> MyModel(array=np.ones((3, 3), dtype=np.uint8))

Not valid:

>>> MyModel(array=dask.array.ones((3, 3), dtype=np.uint8))
Parameters:

  • shape (Shape | str | tuple) – The shape specification, either as a Shape class, or as the shape constraint string/tuple by itself.

  • dtype

Returns:

class Shape(*args: str | int)[source]

A container for shape expressions that describe the shape of an multi dimensional array.

Simple example:

>>> Shape['2, 2']
Shape['2, 2']

A Shape can be compared to a typing.Literal. You can use Literals in NDArray as well.

>>> from typing import Literal

>>> Shape['2, 2'] == Literal['2, 2']
True

A Shape can be constructed by calling for type checker compatibility

>>> Shape['2, 2'] == Shape('2, 2')

And its arguments can be pased as *args, with ints and strings as appropriate

>>> Shape(2, 2, "...") == Shape("2, 2, ...")

Create a new Shape as a callable

static __new__(cls, *args: str | int) → type[~numpydantic.validation.shape.Shape[*, ...]][source]

Create a new Shape as a callable