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:

passing the array argument and returning it from each.

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

validate_dtype(array: NDArrayType) → NDArrayType[source]

Validate the dtype of the given array, returning it unmutated.

Raises:

DtypeError –

validate_shape(array: NDArrayType) → NDArrayType[source]

Validate the shape of the given array, returning it unmutated

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.