pyvista-validation 0.1.0__py3-none-any.whl

pyvista_validation/__init__.py

@@ -0,0 +1,36 @@
+"""Input validation functions."""
+
+from __future__ import annotations
+
+from .check import check_contains as check_contains
+from .check import check_finite as check_finite
+from .check import check_greater_than as check_greater_than
+from .check import check_instance as check_instance
+from .check import check_integer as check_integer
+from .check import check_iterable as check_iterable
+from .check import check_iterable_items as check_iterable_items
+from .check import check_length as check_length
+from .check import check_less_than as check_less_than
+from .check import check_ndim as check_ndim
+from .check import check_nonnegative as check_nonnegative
+from .check import check_number as check_number
+from .check import check_range as check_range
+from .check import check_real as check_real
+from .check import check_sequence as check_sequence
+from .check import check_shape as check_shape
+from .check import check_sorted as check_sorted
+from .check import check_string as check_string
+from .check import check_subdtype as check_subdtype
+from .check import check_type as check_type
+from .validate import validate_array as validate_array
+from .validate import validate_array3 as validate_array3
+from .validate import validate_arrayN as validate_arrayN
+from .validate import validate_arrayN_unsigned as validate_arrayN_unsigned
+from .validate import validate_arrayNx3 as validate_arrayNx3
+from .validate import validate_axes as validate_axes
+from .validate import validate_data_range as validate_data_range
+from .validate import validate_dimensionality as validate_dimensionality
+from .validate import validate_number as validate_number
+from .validate import validate_rotation as validate_rotation
+from .validate import validate_transform3x3 as validate_transform3x3
+from .validate import validate_transform4x4 as validate_transform4x4

pyvista_validation/_cast_array.py

@@ -0,0 +1,134 @@
+"""Array casting functions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import numpy.typing as npt
+
+if TYPE_CHECKING:
+    from pyvista_validation._typing import ArrayLike
+    from pyvista_validation._typing import NumberType
+    from pyvista_validation._typing import NumpyArray
+    from pyvista_validation._typing import _ArrayLikeOrScalar
+    from pyvista_validation._typing import _FiniteNestedList
+    from pyvista_validation._typing import _FiniteNestedTuple
+
+
+def _cast_to_list(
+    arr: _ArrayLikeOrScalar[NumberType],
+) -> NumberType | _FiniteNestedList[NumberType]:
+    """Cast an array to a nested list.
+
+    Parameters
+    ----------
+    arr : float | ArrayLike[float]
+        Array to cast.
+
+    Returns
+    -------
+    list
+        List or nested list array.
+
+    """
+    return _cast_to_numpy(arr).tolist()
+
+
+def _cast_to_tuple(
+    arr: ArrayLike[NumberType],
+) -> NumberType | _FiniteNestedTuple[NumberType]:
+    """Cast an array to a nested tuple.
+
+    Parameters
+    ----------
+    arr : float | ArrayLike[float]
+        Array to cast.
+
+    Returns
+    -------
+    tuple
+        Tuple or nested tuple array.
+
+    """
+    arr = _cast_to_numpy(arr).tolist()
+
+    def _to_tuple(s):
+        return tuple(_to_tuple(i) for i in s) if isinstance(s, list) else s
+
+    return _to_tuple(arr)
+
+
+def _cast_to_numpy(
+    arr: _ArrayLikeOrScalar[NumberType],
+    /,
+    *,
+    as_any: bool = True,
+    dtype: npt.DTypeLike | None = None,
+    copy: bool = False,
+    must_be_real: bool = False,
+) -> NumpyArray[NumberType]:
+    """Cast array to a NumPy ``ndarray``.
+
+    Object arrays are not allowed but the ``dtype`` is otherwise unchecked by default.
+    String arrays and complex numbers are therefore allowed.
+
+    .. warning::
+
+        Arrays intended for use with vtk should set ``must_be_real=True``
+        since ``numpy_to_vtk`` uses the array values directly without
+        checking for complex arrays.
+
+    Parameters
+    ----------
+    arr : float | ArrayLike[float]
+        Array to cast.
+
+    as_any : bool, default: True
+        Allow subclasses of ``np.ndarray`` to pass through without
+        making a copy.
+
+    dtype : npt.typing.DTypeLike, optional
+        The data-type of the returned array.
+
+    copy : bool, default: False
+        If ``True``, a copy of the array is returned. A copy is always
+        returned if the array:
+
+            * is a nested sequence
+            * is a subclass of ``np.ndarray`` and ``as_any`` is ``False``.
+
+    must_be_real : bool, default: True
+        Raise a ``TypeError`` if the array does not have real numbers, that is
+        its data type is not integer or floating.
+
+    Raises
+    ------
+    ValueError
+        If input cannot be cast as a NumPy ``ndarray``.
+    TypeError
+        If an object array is created or if the data is not real numbers
+        and ``must_be_real`` is ``True``.
+
+    Returns
+    -------
+    np.ndarray
+        NumPy ``ndarray``.
+
+    """
+    try:
+        out = np.asanyarray(arr, dtype=dtype) if as_any else np.asarray(arr, dtype=dtype)
+
+        if copy and out is arr:
+            # we requested a copy but didn't end up with one
+            out = out.copy()
+    except ValueError as e:
+        msg = f'Input cannot be cast as {np.ndarray}.'
+        raise ValueError(msg) from e
+    if must_be_real and not issubclass(out.dtype.type, (np.floating, np.integer)):
+        msg = f'Array must have real numbers. Got dtype {out.dtype.type}'
+        raise TypeError(msg)
+    if out.dtype.kind == 'O':
+        msg = f'Object arrays are not supported. Got {arr} when casting to a NumPy array.'
+        raise TypeError(msg)
+    return out

pyvista_validation/_lazy_import.py

@@ -0,0 +1,46 @@
+"""Lazily imported names from this package's optional dependencies.
+
+VTK and SciPy are both optional and both slow to import, so their names are
+resolved from their own submodules on first access and then cached in this
+module's globals. Importing from ``vtkmodules`` rather than ``vtk`` keeps the
+cost to the one submodule a name actually lives in.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+from typing import Any
+
+if TYPE_CHECKING:
+    from scipy.spatial.transform import Rotation
+    from vtkmodules.vtkCommonMath import vtkMatrix3x3
+    from vtkmodules.vtkCommonMath import vtkMatrix4x4
+    from vtkmodules.vtkCommonTransforms import vtkTransform
+
+__all__ = ['Rotation', 'vtkMatrix3x3', 'vtkMatrix4x4', 'vtkTransform']
+
+_MODULES = {
+    'Rotation': 'scipy.spatial.transform',
+    'vtkMatrix3x3': 'vtkmodules.vtkCommonMath',
+    'vtkMatrix4x4': 'vtkmodules.vtkCommonMath',
+    'vtkTransform': 'vtkmodules.vtkCommonTransforms',
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Import a name from its optional dependency, caching it for next time."""
+    if name not in _MODULES:
+        msg = f'module {__name__!r} has no attribute {name!r}'
+        raise AttributeError(msg)
+
+    try:
+        value: Any = getattr(importlib.import_module(_MODULES[name]), name)
+    except ModuleNotFoundError:
+        # No object of this type can exist without its package installed. A
+        # placeholder class is never an instance and still composes into the
+        # `Union` type aliases, unlike None or an empty tuple.
+        value = type(name, (), {})
+
+    globals()[name] = value  # __getattr__ only runs on a miss, so this caches
+    return value

pyvista_validation/_typing/__init__.py

@@ -0,0 +1,15 @@
+"""Type aliases for type hints."""
+
+from __future__ import annotations
+
+from ._aliases import ArrayLike as ArrayLike
+from ._aliases import MatrixLike as MatrixLike
+from ._aliases import Number as Number
+from ._aliases import RotationLike as RotationLike
+from ._aliases import TransformLike as TransformLike
+from ._aliases import VectorLike as VectorLike
+from ._aliases import _ArrayLikeOrScalar as _ArrayLikeOrScalar
+from ._array_like import NumberType as NumberType
+from ._array_like import NumpyArray as NumpyArray
+from ._array_like import _FiniteNestedList as _FiniteNestedList
+from ._array_like import _FiniteNestedTuple as _FiniteNestedTuple

pyvista_validation/_typing/_aliases.py

@@ -0,0 +1,23 @@
+"""Core type aliases."""
+
+from __future__ import annotations
+
+from typing import Union
+
+from pyvista_validation import _lazy_import
+
+from ._array_like import NumberType
+from ._array_like import _ArrayLike
+from ._array_like import _ArrayLike1D
+from ._array_like import _ArrayLike2D
+
+Number = Union[int, float]
+VectorLike = _ArrayLike1D[NumberType]
+MatrixLike = _ArrayLike2D[NumberType]
+ArrayLike = _ArrayLike[NumberType]
+
+RotationLike = Union[MatrixLike[float], _lazy_import.vtkMatrix3x3, _lazy_import.Rotation]
+TransformLike = Union[RotationLike, _lazy_import.vtkMatrix4x4, _lazy_import.vtkTransform]
+
+# Undocumented alias - should be expanded in docs
+_ArrayLikeOrScalar = Union[NumberType, ArrayLike[NumberType]]

pyvista_validation/_typing/_array_like.py

@@ -0,0 +1,86 @@
+"""Generic array-like type definitions.
+
+Definitions here are loosely based on code in ``numpy._typing._array_like``.
+Some key differences include:
+
+- Some npt._array_like definitions explicitly support dual-types for
+  handling Python and NumPy scalar data types separately.
+  Here, only a single generic type is used for simplicity.
+
+- The npt._array_like definitions use a recursive _NestedSequence protocol.
+  Here, finite sequences are used instead.
+
+- The npt._array_like definitions use a generic _SupportsArray protocol.
+  Here, we use ``ndarray`` directly.
+
+- The npt._array_like definitions include scalar types (for example, float, int).
+  Here they are excluded (that is, scalars are not considered to be arrays).
+
+- The npt._array_like TypeVar is bound to np.generic. Here, the
+  TypeVar is bound to a subset of numeric types only.
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TypeVar
+from typing import Union
+
+import numpy as np
+import numpy.typing as npt
+
+# Define numeric types
+NumberType = TypeVar(
+    'NumberType',
+    bound=np.floating | np.integer | np.bool_ | float | int | bool,
+)
+
+# Create a copy of the typevar which can be used for annotating a second variable.
+# Its definition should be identical to `NumberType`
+_NumberType = TypeVar(  # noqa: PYI018
+    '_NumberType',
+    bound=np.floating | np.integer | np.bool_ | float | int | bool,
+)
+
+NumpyArray = npt.NDArray[NumberType]
+
+_FiniteNestedList = (
+    list[NumberType]
+    | list[list[NumberType]]
+    | list[list[list[NumberType]]]
+    | list[list[list[list[NumberType]]]]
+)
+_FiniteNestedTuple = (
+    tuple[NumberType]
+    | tuple[tuple[NumberType]]
+    | tuple[tuple[tuple[NumberType]]]
+    | tuple[tuple[tuple[tuple[NumberType]]]]
+)
+
+_ArrayLike1D = Union[
+    NumpyArray[NumberType],
+    Sequence[NumberType],
+    Sequence[NumpyArray[NumberType]],
+]
+_ArrayLike2D = Union[
+    NumpyArray[NumberType],
+    Sequence[Sequence[NumberType]],
+    Sequence[Sequence[NumpyArray[NumberType]]],
+]
+_ArrayLike3D = Union[
+    NumpyArray[NumberType],
+    Sequence[Sequence[Sequence[NumberType]]],
+    Sequence[Sequence[Sequence[NumpyArray[NumberType]]]],
+]
+_ArrayLike4D = Union[
+    NumpyArray[NumberType],
+    Sequence[Sequence[Sequence[Sequence[NumberType]]]],
+    Sequence[Sequence[Sequence[Sequence[NumpyArray[NumberType]]]]],
+]
+_ArrayLike = Union[
+    _ArrayLike1D[NumberType],
+    _ArrayLike2D[NumberType],
+    _ArrayLike3D[NumberType],
+    _ArrayLike4D[NumberType],
+]

pyvista_validation/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'g623faa28b'