pyvista-validation

Validate and standardize array-like input.

These are the input validation functions developed for PyVista, extracted into a standalone package so any project can use them. NumPy is the only required dependency: PyVista is not needed, and VTK and SciPy are optional.

The functions are useful when writing Python methods that accept flexible array-like input, wrapping VTK, or anywhere you want one standard representation out of many possible inputs.

Warning — The API of this package is unstable and likely to change between minor versions (for example 0.1.0 to 0.2.0). Pin the exact version you depend on, for example pyvista-validation==0.1.0.

Installation

pip install pyvista-validation

VTK and SciPy are only needed to validate their own object types, so they ship as extras:

pip install pyvista-validation[vtk]    # accept vtkMatrix3x3, vtkMatrix4x4, vtkTransform
pip install pyvista-validation[scipy]  # accept scipy.spatial.transform.Rotation
pip install pyvista-validation[all]    # both

Neither is imported unless you actually pass one of their objects in.

The wheels carry a C extension that runs the checks; the package works the same without it, from the source distribution or with PYVISTA_VALIDATION_ACCELERATE=false in the environment.

Two families of function

A check function:

• Performs a simple validation on a single input variable.
• Raises an error if the check fails due to invalid input.
• Does not modify its input, and returns it unchanged, typed as what the check established, so a check can be used inline.

A validate function:

• Uses check functions to check the type and/or value of input arguments.
• Applies optional constraints -- for example input or output must have a specific length, shape, type, data-type, etc.
• Accepts many different input types or values and standardizes the output as a single representation with known properties.

Usage

validate functions return a standard representation:

>>> import numpy as np
>>> from pyvista_validation import validate_array3
>>> from pyvista_validation import validate_arrayNx3
>>> from pyvista_validation import validate_data_range

>>> validate_array3([1, 2, 3])
array([1, 2, 3])

>>> validate_arrayNx3([[1, 2, 3], [4, 5, 6]])
array([[1, 2, 3],
       [4, 5, 6]])

>>> validate_data_range([0, 1])
(0, 1)

A 3x3 input to validate_transform4x4 is padded into a 4x4 matrix:

>>> from pyvista_validation import validate_transform4x4

>>> validate_transform4x4(np.eye(3))
array([[1., 0., 0., 0.],
       [0., 1., 0., 0.],
       [0., 0., 1., 0.],
       [0., 0., 0., 1.]])

validate_array is the general-purpose entry point that the others build on, and takes the constraints as keyword arguments:

>>> from pyvista_validation import validate_array

>>> validate_array(
...     [1, 2, 3], must_have_shape=(3,), must_be_in_range=[0, 5], dtype_out=float
... )
array([1., 2., 3.])

check functions return their input unchanged and raise on failure:

>>> from pyvista_validation import check_range
>>> from pyvista_validation import check_subdtype

>>> check_range([1, 5], rng=[0, 3])
Traceback (most recent call last):
    ...
ValueError: Array values must all be less than or equal to 3.

>>> check_subdtype(np.array([1.0]), np.integer)
Traceback (most recent call last):
    ...
TypeError: Input has incorrect dtype of 'float64'. The dtype must be a subtype of <class 'numpy.integer'>.

Error messages name the offending value and the constraint it violated:

>>> validate_array3([1, 2])
Traceback (most recent call last):
    ...
ValueError: Array has shape (2,) which is not allowed. Shape must be one of [(3,), (1, 3), (3, 1)].

Pass name= to any function to control how the input is described in that message.

Common use cases

API reference

validate functions

check functions

Every function has a full docstring with parameters and examples.

Relationship to PyVista

This code began as pyvista.core._validation and keeps its full commit history here. PyVista is a downstream consumer, and CI installs this checkout into PyVista and runs PyVista's own core test suite against it on every change.

One PyVista-specific helper, _validate_color_sequence, was not moved: it is built on pyvista.plotting's Color class and stays with PyVista.

License

MIT