Interfaces

Base Interface metaclass

class Interface(shape: Tuple[int, ...] | Any, dtype: str | type | Any | generic)[source]

Abstract parent class for interfaces to different array formats

validate(array: Any) → T[source]

Validate input, returning final array type

Calls the methods, in order:

  • array = before_validation() (array)

  • dtype = get_dtype() (array) - get the dtype from the array,

    override if eg. the dtype is not contained in array.dtype

  • valid = validate_dtype() (dtype) - check that the dtype matches

    the one in the NDArray specification. Override if special validation logic is needed for a given format

  • raise_for_dtype() (valid, dtype) - after checking dtype validity,

    raise an exception if it was invalid. Override to implement custom exceptions or error conditions, or make validation errors conditional.

  • array = after_validate_dtype() (array) - hook for additional

    validation or array modification mid-validation

  • shape = get_shape() (array) - get the shape from the array,

    override if eg. the shape is not contained in array.shape

  • valid = validate_shape() (shape) - check that the shape matches

    the one in the NDArray specification. Override if special validation logic is needed.

  • raise_for_shape() (valid, shape) - after checking shape validity,

    raise an exception if it was invalid. You know the deal bc it’s the same as raise for dtype.

  • after_validation() - hook after validation for modifying the array

    that is set as the model field value

Follow the method signatures and return types to override.

Implementing an interface subclass largely consists of overriding these methods as needed.

Raises:

  • If validation fails, rather than eg. returning False, exceptions will –

  • be raised (to halt the rest of the pydantic validation process). –

  • When using interfaces outside of pydantic, you must catch both –

  • .DtypeError –

:raises of InterfaceError ):

before_validation(array: Any) → NDArrayType[source]

Optional step pre-validation that coerces the input into a type that can be validated for shape and dtype

Default method is a no-op

get_dtype(array: NDArrayType) → str | type | Any | generic[source]

Get the dtype from the input array

get_object_dtype(array: NDArrayType) → str | type | Any | generic[source]

When an array contains an object, get the dtype of the object contained by the array.

validate_dtype(dtype: str | type | Any | generic) → bool[source]

Validate the dtype of the given array, returning True if valid, False if not.

raise_for_dtype(valid: bool, dtype: str | type | Any | generic) → None[source]

After validating, raise an exception if invalid :raises ~numpydantic.exceptions.DtypeError:

after_validate_dtype(array: NDArrayType) → NDArrayType[source]

Hook to modify array after validating dtype. Default is a no-op.

get_shape(array: NDArrayType) → Tuple[int, ...][source]

Get the shape from the array as a tuple of integers

validate_shape(shape: Tuple[int, ...]) → bool[source]

Validate the shape of the given array against the shape specifier, returning True if valid, False if not.

raise_for_shape(valid: bool, shape: Tuple[int, ...]) → None[source]

Raise a ShapeError if the shape is invalid.

Raises:

ShapeError –

after_validation(array: NDArrayType) → T[source]

Optional step post-validation that coerces the intermediate array type into the return type

Default method is a no-op

abstract classmethod check(array: Any) → bool[source]

Method to check whether a given input applies to this interface

abstract classmethod enabled() → bool[source]

Check whether this array interface can be used (eg. its dependent packages are installed, etc.)

classmethod to_json(array: Type[T], info: SerializationInfo | None = None) → list | dict[source]

Convert an array of return_type to a JSON-compatible format using base python types

classmethod interfaces(with_disabled: bool = False, sort: bool = True) → Tuple[Type[Interface], ...][source]

Enabled interface subclasses

Parameters:

  • with_disabled (bool) – If True , get every known interface. If False (default), get only enabled interfaces.

  • sort (bool) – If True (default), sort interfaces by priority. If False , sorted by definition order. Used for recursion: we only want to sort once at the top level.

classmethod return_types() → Tuple[NDArrayType, ...][source]

Return types for all enabled interfaces

classmethod input_types() → Tuple[Any, ...][source]

Input types for all enabled interfaces

classmethod match(array: Any, fast: bool = False) → Type[Interface][source]

Find the interface that should be used for this array based on its input type

First runs the check method for all interfaces returned by Interface.interfaces() except for NumpyInterface , and if no match is found then try the numpy interface. This is because NumpyInterface.check() can be expensive, as we could potentially try to

Parameters:

fast (bool) – if False , check all interfaces and raise exceptions for having multiple matching interfaces (default). If True , check each interface (as ordered by its priority , decreasing), and return on the first match.

classmethod match_output(array: Any) → Type[Interface][source]

Find the interface that should be used based on the output type - in the case that the output type differs from the input type, eg. the HDF5 interface, match an instantiated array for purposes of serialization to json, etc.