Interfaces¶
Interfaces are the bridge between the abstract NDArray specification
and concrete array libraries. They are subclasses of the abstract Interface
class.
They contain methods for coercion, validation, serialization, and any other implementation-specific functionality.
Discovery¶
Interfaces are discovered through the Interface.interfaces() method -
returning all subclasses of Interface. To use a custom interface, it just
needs to be defined/imported by the time you intend to use it when instantiating
a pydantic model.
Each interface implements a Interface.enabled() method that determines
whether that interface can be used. Typically that means checking if its dependencies
are present in the environment, but can also control conditional use.
Matching¶
When a pydantic model is instantiated and an NDArray is to be validated,
Interface.match() first, uh, finds the matching interface.
Each interface must define a Interface.check() class that accepts the
array to be validated and returns whether it can be used. Interfaces can
have any checking logic they want, and so can eg. determine if a path
is a particular type of file, but should return quickly and do little work
since they are called frequently.
Validation fails if an argument doesn’t match any interface.
Note
The NumpyInterface is special cased and is only checked if
no other interface matches. It attempts to cast the input argument to a
numpy.ndarray to see if it is arraylike, and since many
lazy-loaded array libraries will attempt to load the whole array into memory
when cast to an ndarray, we only try as a last resort.
Validation¶
Validation is a chain of lifecycle methods, each of which can be overridden for interfaces to implement custom behavior that matches the array format.
Interface.validate() calls the following methods, in order:
A method to deserialize the array dumped with a model_dump_json()
with round_trip = True (see serialization)
An initial hook for modifying the input data before validation, eg.
if it needs to be coerced or wrapped in some proxy class. This method
should accept all and only the types specified in that interface’s
input_types.
A cluster of methods for validating dtype. Separating these methods allow for array formats that store dtype information in a nonstandard attribute, require additional coercion, or for implementing custom exception handlers or rescuers. Check the method signatures and return types when overriding and the docstrings for details.
A halftime hook for modifying the array or bailing early between validation phases.
A cluster of methods for validating shape, similar to the dtype cluster.
A final hook for modifying the array before passing it to be assigned to the field.
This method should return an object matching the interface’s return_type.
Diagram¶
Todo
Sorry this is unreadable, need to recall how to change the theme for generated mermaid diagrams but it is very late and i want to push this.