"""Functions that check the type and/or value of inputs. .. versionadded:: 0.43.0 A ``check`` function typically: * Performs a simple validation on a single input variable. * Raises an error if the check fails due to invalid input. * Does not modify input or return anything. """ from __future__ import annotations from collections.abc import Container from collections.abc import Iterable from collections.abc import Sequence from collections.abc import Sized from numbers import Number import reprlib import types from typing import TYPE_CHECKING from typing import Any from typing import Union from typing import cast from typing import get_args from typing import get_origin import numpy as np import numpy.typing as npt from pyvista.core._validation._cast_array import _cast_to_numpy if TYPE_CHECKING: from pyvista.core._typing_core import NumberType from pyvista.core._typing_core import NumpyArray from pyvista.core._typing_core import VectorLike from pyvista.core._typing_core._aliases import _ArrayLikeOrScalar from pyvista.core._typing_core._array_like import _NumberType _Shape = tuple[()] | tuple[int, ...] _ShapeLike = int | _Shape def check_subdtype( input_obj: npt.DTypeLike | _ArrayLikeOrScalar[NumberType], /, base_dtype: npt.DTypeLike | tuple[npt.DTypeLike, ...] | list[npt.DTypeLike], *, name: str = 'Input', ) -> None: """Check if an input's data-type is a subtype of another data-type(s). Parameters ---------- input_obj : float | ArrayLike[float] | numpy.typing.DTypeLike ``dtype`` object (or object coercible to one) or an array-like object. If array-like, the dtype of the array is used. base_dtype : numpy.typing.DTypeLike | Sequence[numpy.typing.DTypeLike] ``dtype``-like object or a sequence of ``dtype``-like objects. The ``input_obj`` must be a subtype of this value. If a sequence, ``input_obj`` must be a subtype of at least one of the specified dtypes. name : str, default: "Input" Variable name to use in the error messages if any are raised. Raises ------ TypeError If ``input_obj`` is not a subtype of ``base_dtype``. See Also -------- check_real check_number Examples -------- Check if ``float`` is a subtype of ``np.floating``. >>> import numpy as np >>> from pyvista import _validation >>> _validation.check_subdtype(float, np.floating) Check from multiple allowable dtypes. >>> _validation.check_subdtype(int, [np.integer, np.floating]) Check an array's dtype. >>> array = np.array([1, 2, 3], dtype='uint8') >>> _validation.check_subdtype(array, np.integer) """ input_dtype: npt.DTypeLike try: input_dtype = np.dtype(input_obj) # type: ignore[arg-type] except TypeError: input_dtype = np.asanyarray(input_obj).dtype if not isinstance(base_dtype, (tuple, list)): base_dtype = [base_dtype] if not any(np.issubdtype(input_dtype, base) for base in base_dtype): # Not a subdtype, so raise error msg = f"{name} has incorrect dtype of '{input_dtype.name}'. " if len(base_dtype) == 1: msg += f'The dtype must be a subtype of {base_dtype[0]}.' else: msg += f'The dtype must be a subtype of at least one of \n{base_dtype}.' raise TypeError(msg) def check_real(array: _ArrayLikeOrScalar[NumberType], /, *, name: str = 'Array') -> None: """Check if an array has real numbers, i.e. float or integer type. Notes ----- - Boolean data types are not considered real and will raise an error. - Arrays with ``infinity`` or ``NaN`` values are considered real and will not raise an error. Use :func:`check_finite` to check for finite values. Parameters ---------- array : float | ArrayLike[float] Number or array to check. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ TypeError If the array does not have real numbers. See Also -------- check_integer Similar function for integer arrays. check_number Similar function for scalar values. check_finite Check for finite values. Examples -------- Check if an array has real numbers. >>> from pyvista import _validation >>> _validation.check_real([1, 2, 3]) """ array = array if isinstance(array, np.ndarray) else _cast_to_numpy(array) # Return early for common cases if array.dtype.type in [np.int32, np.int64, np.float32, np.float64]: return # Do not use np.isreal as it will fail in some cases (e.g. scalars). # Check dtype directly instead try: check_subdtype(array, (np.floating, np.integer), name=name) except TypeError as e: msg = f'{name} must have real numbers.' raise TypeError(msg) from e def check_sorted( array: _ArrayLikeOrScalar[NumberType], /, *, ascending: bool = True, strict: bool = False, axis: int = -1, name: str = 'Array', ) -> None: """Check if an array's values are sorted. Parameters ---------- array : float | ArrayLike[float] Number or array to check. ascending : bool, default: True If ``True``, check if the array's elements are in ascending order. If ``False``, check if the array's elements are in descending order. strict : bool, default: False If ``True``, the array's elements must be strictly increasing (if ``ascending=True``) or strictly decreasing (if ``ascending=False``). Effectively, this means the array must be sorted *and* its values must be unique. axis : int | None, default: -1 Axis along which to check sorting. If ``None``, the array is flattened before checking. The default is ``-1``, which checks sorting along the last axis. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If the array is not sorted in ascending order. See Also -------- check_range Examples -------- Check if an array's values are sorted, >>> from pyvista import _validation >>> _validation.check_sorted([1, 2, 3]) """ array = array if isinstance(array, np.ndarray) else _cast_to_numpy(array) ndim = array.ndim if ndim == 0: # Scalars are always sorted return # Validate axis if axis not in [-1, None]: check_number(axis, name='Axis') check_integer(axis, name='Axis') axis = int(axis) try: check_range(axis, rng=[-ndim, ndim - 1], name='Axis') except ValueError: msg = f'Axis {axis} is out of bounds for ndim {ndim}.' raise ValueError(msg) if axis is None and ndim >= 1: # type: ignore[unreachable] # Emulate np.sort(), which flattens array when axis is None array = array.ravel(order='A') # type: ignore[unreachable] ndim = 1 axis = 0 # Create slicers to get a view along an axis # Create two slicers to compare consecutive elements with each other first_slice = [slice(None)] * ndim first_slice[axis] = slice(None, -1) first_item = array[tuple(first_slice)] second_slice = [slice(None)] * ndim second_slice[axis] = slice(1, None) second_item = array[tuple(second_slice)] if ascending and not strict: is_sorted = np.all(first_item <= second_item) elif ascending and strict: is_sorted = np.all(first_item < second_item) elif not ascending and not strict: is_sorted = np.all(first_item >= second_item) else: # not ascending and strict is_sorted = np.all(first_item > second_item) if not is_sorted: # Show the array's elements in error msg if array is small msg_body = f'with {array.size} elements' order = 'ascending' if ascending else 'descending' strict_ = 'strict ' if strict else '' msg = ( f'{name} {msg_body} must be sorted in {strict_}{order} order. ' f'Got:\n {reprlib.repr(array)}' ) raise ValueError(msg) def check_finite(array: _ArrayLikeOrScalar[NumberType], /, *, name: str = 'Array') -> None: """Check if an array has finite values, i.e. no NaN or Inf values. Parameters ---------- array : float | ArrayLike[float] Number or array to check. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If the array has any ``Inf`` or ``NaN`` values. See Also -------- check_real Examples -------- Check if an array's values are finite. >>> from pyvista import _validation >>> _validation.check_finite([1, 2, 3]) """ array = array if isinstance(array, np.ndarray) else _cast_to_numpy(array) if not np.all(np.isfinite(array)): msg = f'{name} must have finite values.' raise ValueError(msg) def check_integer( array: _ArrayLikeOrScalar[NumberType], /, *, strict: bool = False, name: str = 'Array', ) -> None: """Check if an array has integer or integer-like float values. Parameters ---------- array : float | ArrayLike[float] Number or array to check. strict : bool, default: False If ``True``, the array's data must be a subtype of `int` or ``np.integer``. Otherwise, floats are allowed but must be whole numbers. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If any element's value differs from its floor. TypeError If ``strict=True`` and the array's dtype is not integral. See Also -------- check_nonnegative check_subdtype Examples -------- Check if an array has integer-like values. >>> from pyvista import _validation >>> _validation.check_integer([1.0, 2.0]) """ array = array if isinstance(array, np.ndarray) else _cast_to_numpy(array) if strict: check_subdtype(array, np.integer) elif not np.array_equal(array, np.floor(array)): msg = f'{name} must have integer-like values.' raise ValueError(msg) def check_nonnegative(array: _ArrayLikeOrScalar[NumberType], /, *, name: str = 'Array') -> None: """Check if an array's elements are all nonnegative. Parameters ---------- array : float | ArrayLike[float] Number or array to check. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If the array has any negative values. See Also -------- check_greater_than check_less_than Examples -------- Check if an array's values are non-negative. >>> from pyvista import _validation >>> _validation.check_nonnegative([1, 2, 3]) """ check_greater_than(array, 0, strict=False, name=name) def _validate_real_value(scalar: float, name: str = 'Value') -> NumpyArray[float]: valid_scalar = _cast_to_numpy(scalar) check_shape(valid_scalar, (), name=name) check_real(valid_scalar, name=name) return valid_scalar def check_greater_than( array: _ArrayLikeOrScalar[NumberType], /, value: float, *, strict: bool = True, name: str = 'Array', ) -> None: """Check if an array's elements are all greater than some value. Parameters ---------- array : float | ArrayLike[float] Number or array to check. value : float Value which the array's elements must be greater than. strict : bool, default: True If ``True``, the array's value must be strictly greater than ``value``. Otherwise, values must be greater than or equal to ``value``. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If not all array elements are greater than (or equal to if ``strict=True``) the specified value. See Also -------- check_less_than check_range check_nonnegative Examples -------- Check if an array's values are greater than 0. >>> from pyvista import _validation >>> _validation.check_greater_than([1, 2, 3], value=0) """ array = array if isinstance(array, np.ndarray) else _cast_to_numpy(array) valid_value = _validate_real_value(value) if strict and not np.all(array > valid_value): msg = f'{name} values must all be greater than {value}.' raise ValueError(msg) elif not np.all(array >= valid_value): msg = f'{name} values must all be greater than or equal to {value}.' raise ValueError(msg) def check_less_than( array: _ArrayLikeOrScalar[NumberType], /, value: float, *, strict: bool = True, name: str = 'Array', ) -> None: """Check if an array's elements are all less than some value. Parameters ---------- array : float | ArrayLike[float] Number or array to check. value : float Value which the array's elements must be less than. strict : bool, default: True If ``True``, the array's value must be strictly less than ``value``. Otherwise, values must be less than or equal to ``value``. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If not all array elements are less than (or equal to if ``strict=True``) the specified value. See Also -------- check_greater_than check_range check_nonnegative Examples -------- Check if an array's values are less than 0. >>> from pyvista import _validation >>> _validation.check_less_than([-1, -2, -3], value=0) """ array = array if isinstance(array, np.ndarray) else _cast_to_numpy(array) valid_value = _validate_real_value(value) if strict and not np.all(array < valid_value): msg = f'{name} values must all be less than {value}.' raise ValueError(msg) elif not np.all(array <= valid_value): msg = f'{name} values must all be less than or equal to {value}.' raise ValueError(msg) def check_range( array: _ArrayLikeOrScalar[NumberType], /, rng: VectorLike[_NumberType], *, strict_lower: bool = False, strict_upper: bool = False, name: str = 'Array', ) -> None: """Check if an array's values are all within a specific range. Parameters ---------- array : float | ArrayLike[float] Number or array to check. rng : VectorLike[float], optional Vector with two elements ``[min, max]`` specifying the minimum and maximum data values allowed, respectively. By default, the range endpoints are inclusive, i.e. values must be >= min and <= max. Use ``strict_lower`` and/or ``strict_upper`` to further restrict the allowable range. Use ``np.inf`` or ``-np.inf`` to specify open intervals, e.g. ``[0, np.inf]``. strict_lower : bool, default: False Enforce a strict lower bound for the range, i.e. array values must be strictly greater than the minimum. strict_upper : bool, default: False Enforce a strict upper bound for the range, i.e. array values must be strictly less than the maximum. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If any array value is outside the specified range. See Also -------- check_less_than check_greater_than Examples -------- Check if `an array's values are in the range ``[0, 1]``. >>> from pyvista import _validation >>> _validation.check_range([0, 0.5, 1], rng=[0, 1]) """ rng = rng if isinstance(rng, np.ndarray) else _cast_to_numpy(rng) check_shape(rng, 2, name='Range') check_sorted(rng, name='Range') array = array if isinstance(array, np.ndarray) else _cast_to_numpy(array) check_greater_than(array, rng[0], strict=strict_lower, name=name) check_less_than(array, rng[1], strict=strict_upper, name=name) def check_shape( array: _ArrayLikeOrScalar[NumberType], /, shape: _ShapeLike | list[_ShapeLike], *, name: str = 'Array', ) -> None: """Check if an array has the specified shape. Parameters ---------- array : float | ArrayLike[float] Number or array to check. shape : ShapeLike | list[ShapeLike] A single shape or a list of any allowable shapes. If an integer, ``i``, the shape is interpreted as ``(i,)``. Use a value of -1 for any dimension where its size is allowed to vary, e.g. ``(-1,3)`` if any Nx3 array is allowed. Use ``()`` for the shape of scalar values (i.e. 0-dimensional). If a list, the array must have at least one of the specified shapes. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If the array does not have any of the specified shape(s). See Also -------- check_length check_ndim Examples -------- Check if an array is one-dimensional. >>> import numpy as np >>> from pyvista import _validation >>> _validation.check_shape([1, 2, 3], shape=(-1)) Check if an array is one-dimensional or a scalar. >>> _validation.check_shape(1, shape=[(), (-1)]) Check if an array is 3x3 or 4x4. >>> _validation.check_shape(np.eye(3), shape=[(3, 3), (4, 4)]) """ def _shape_is_allowed(a: _Shape, b: _Shape) -> bool: # a: array's actual shape # b: allowed shape (may have -1) return len(a) == len(b) and all(map(lambda x, y: True if x == y else y == -1, a, b)) if not isinstance(shape, list): shape = [shape] array_shape = np.shape(array) # type: ignore[arg-type] for input_shape in shape: valid_shape = _validate_shape_value(input_shape) if _shape_is_allowed(array_shape, valid_shape): return msg = f'{name} has shape {array_shape} which is not allowed. ' if len(shape) == 1: msg += f'Shape must be {shape[0]}.' else: msg += f'Shape must be one of {shape}.' raise ValueError(msg) def check_ndim( array: _ArrayLikeOrScalar[NumberType], /, ndim: int | VectorLike[int], *, name: str = 'Array', ) -> None: """Check if an array has the specified number of dimensions. .. note:: Scalar values have a dimension of ``0``. Parameters ---------- array : float | ArrayLike[float] Number or array to check. ndim : int | Sequence[int], optional A single dimension or a sequence of allowable dimensions. If an integer, the array must have this number of dimension(s). If a sequence, the array must have at least one of the specified number of dimensions. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If the array does not have the required number of dimensions. See Also -------- check_length check_shape Examples -------- Check if an array is one-dimensional >>> import numpy as np >>> from pyvista import _validation >>> _validation.check_ndim([1, 2, 3], ndim=1) Check if an array is two-dimensional or a scalar. >>> _validation.check_ndim(1, ndim=(0, 2)) """ ndim_ = np.atleast_1d(ndim) array_ndim = _cast_to_numpy(array).ndim if array_ndim not in ndim_: check_ndim(ndim, [0, 1], name='ndim') if len(ndim_) == 1: check_integer(ndim_[0], strict=True, name='ndim') expected = f'{ndim}' else: check_integer(ndim, strict=True, name='ndim') expected = f'one of {ndim}' msg = ( f'{name} has the incorrect number of dimensions. ' f'Got {array_ndim}, expected {expected}.' ) raise ValueError(msg) def check_number(num: float, /, *, name: str = 'Object') -> None: """Check if an object is an instance of ``Number``. A number is any instance of ``numbers.Number``, e.g. ``int``, ``float``, and ``complex``. Notes ----- A NumPy ndarray is not an instance of ``Number``. Parameters ---------- num : numbers.Number Number to check. name : str, default: "Object" Variable name to use in the error messages if any are raised. Raises ------ TypeError If input is not an instance of ``Number``. Examples -------- Check if a complex number is an instance of ``Number``. >>> from pyvista import _validation >>> _validation.check_number(1 + 2j) """ check_instance(num, Number, allow_subclass=True, name=name) def check_string(obj: str, /, *, allow_subclass: bool = True, name: str = 'Object') -> None: """Check if an object is an instance of ``str``. Parameters ---------- obj : str Object to check. allow_subclass : bool, default: True If ``True``, the object's type must be ``str`` or a subclass of ``str``. Otherwise, subclasses are not allowed. name : str, default: "Object" Variable name to use in the error messages if any are raised. Raises ------ TypeError If input is not an instance of ``str``. See Also -------- check_contains check_iterable_items check_sequence check_instance Examples -------- Check if an object is a string. >>> from pyvista import _validation >>> _validation.check_string('eggs') """ check_instance(obj, str, allow_subclass=allow_subclass, name=name) def check_sequence(obj: Sequence[Any], /, *, name: str = 'Object') -> None: """Check if an object is an instance of ``Sequence``. Parameters ---------- obj : Sequence Object to check. name : str, default: "Object" Variable name to use in the error messages if any are raised. Raises ------ TypeError If input is not an instance of ``Sequence``. See Also -------- check_iterable check_instance Examples -------- Check if an object is a sequence. >>> import numpy as np >>> from pyvista import _validation >>> _validation.check_sequence([1, 2, 3]) >>> _validation.check_sequence('A') """ check_instance(obj, Sequence, allow_subclass=True, name=name) def check_iterable(obj: Iterable[Any], /, *, name: str = 'Object') -> None: """Check if an object is an instance of ``Iterable``. Parameters ---------- obj : Iterable Iterable object to check. name : str, default: "Object" Variable name to use in the error messages if any are raised. Raises ------ TypeError If input is not an instance of ``Iterable``. See Also -------- check_sequence check_instance check_iterable_items Examples -------- Check if an object is iterable. >>> import numpy as np >>> from pyvista import _validation >>> _validation.check_iterable([1, 2, 3]) >>> _validation.check_iterable(np.array((4, 5, 6))) """ check_instance(obj, Iterable, allow_subclass=True, name=name) def check_instance( obj: object, /, classinfo: type | tuple[type, ...], *, allow_subclass: bool = True, name: str = 'Object', ) -> None: """Check if an object is an instance of the given type or types. Parameters ---------- obj : Any Object to check. classinfo : type | tuple[type, ...] ``type`` or tuple of types. Object must be an instance of one of the types. allow_subclass : bool, default: True If ``True``, the object's type must be specified by ``classinfo`` or any of its subclasses. Otherwise, subclasses are not allowed. name : str, default: "Object" Variable name to use in the error messages if any are raised. Raises ------ TypeError If object is not an instance of any of the given types. See Also -------- check_type check_number check_string check_iterable check_sequence Examples -------- Check if an object is an instance of ``complex``. >>> from pyvista import _validation >>> _validation.check_instance(1 + 2j, complex) Check if an object is an instance of one of several types. >>> _validation.check_instance('eggs', (int, str)) """ if not isinstance(name, str): msg = f'Name must be a string, got {type(name)} instead.' # type: ignore[unreachable] raise TypeError(msg) # Get class info from generics origin = get_origin(classinfo) if origin is Union or origin is types.UnionType: classinfo = get_args(classinfo) # Count num classes num_classes = len(classinfo) if isinstance(classinfo, tuple) else 1 # Check if is instance is_instance = isinstance(obj, classinfo) # Set flag to raise error if not instance is_error = False if allow_subclass and not is_instance: is_error = True if num_classes == 1: msg_body = 'must be an instance of' else: msg_body = 'must be an instance of any type' # Set flag to raise error if not type elif not allow_subclass: if isinstance(classinfo, tuple): if type(obj) not in classinfo: is_error = True msg_body = 'must have one of the following types' elif type(obj) is not classinfo: is_error = True msg_body = 'must have type' if is_error: msg = f'{name} {msg_body} {classinfo}. Got {type(obj)} instead.' raise TypeError(msg) def check_type( obj: object, /, classinfo: type | tuple[type, ...], *, name: str = 'Object' ) -> None: """Check if an object is one of the given type or types. Notes ----- The use of :func:`check_instance` is generally preferred as it allows subclasses. Use :func:`check_type` only for cases where exact types are necessary. Parameters ---------- obj : Any Object to check. classinfo : type | tuple[type, ...] ``type`` or tuple of types. Object must be one of the types. name : str, default: "Object" Variable name to use in the error messages if any are raised. Raises ------ TypeError If object is not any of the given types. See Also -------- check_instance Examples -------- Check if an object is type ``dict`` or ``set``. >>> from pyvista import _validation >>> _validation.check_type({'spam': 'eggs'}, (dict, set)) """ check_instance(obj, classinfo, allow_subclass=False, name=name) def check_iterable_items( iterable_obj: Iterable[Any], /, item_type: type | tuple[type, ...], *, allow_subclass: bool = True, name: str = 'Iterable', ) -> None: """Check if an iterable's items all have a specified type. Parameters ---------- iterable_obj : Iterable Iterable to check. item_type : type | tuple[type, ...] Class type(s) to check for. Each element of the sequence must have the type or one of the types specified. allow_subclass : bool, default: True If ``True``, the type of the iterable items must be any of the given types or a subclass thereof. Otherwise, subclasses are not allowed. name : str, default: "Iterable" Variable name to use in the error messages if any are raised. Raises ------ TypeError If any of the items in the iterable have an incorrect type. See Also -------- check_instance check_iterable check_iterable_items Examples -------- Check if a ``tuple`` only has ``int`` or ``float`` elements. >>> from pyvista import _validation >>> _validation.check_iterable_items((1, 2, 3.0), (int, float)) Check if a ``list`` only has ``list`` elements. >>> from pyvista import _validation >>> _validation.check_iterable_items([[1], [2], [3]], list) """ check_iterable(iterable_obj, name=name) any( check_instance( # type: ignore[func-returns-value] item, item_type, allow_subclass=allow_subclass, name=f'All items of {name}', ) for item in iterable_obj ) def check_contains( container: Container[Any], /, must_contain: Any, *, name: str = 'Input' ) -> None: """Check if an item is in a container. Parameters ---------- container : Any Container to check. must_contain : Any Item which must be in the container. name : str, default: "Input" Variable name to use in the error messages if any are raised. Raises ------ ValueError If the item is not in the container. See Also -------- check_iterable check_iterable_items Examples -------- Check if ``"A"`` is in a list of strings. >>> from pyvista import _validation >>> _validation.check_contains(['A', 'B', 'C'], must_contain='A') """ if must_contain not in container: qualifier = 'one of' if isinstance(container, (list, tuple)) else 'in' msg = f"{name} '{must_contain}' is not valid. {name} must be {qualifier}: \n\t{container}" raise ValueError(msg) def check_length( sized_input: float | Sized, /, exact_length: int | VectorLike[int] | None = None, *, min_length: int | None = None, max_length: int | None = None, must_be_1d: bool = False, allow_scalar: bool = False, name: str = 'Array', ) -> None: """Check if the length of an array meets specific requirements. Notes ----- By default, this function operates on multidimensional arrays, where ``len(arr)`` may differ from the number of elements in the array. For one-dimensional cases (where ``len(arr) == arr.size``), set ``must_be_1D=True``. Parameters ---------- sized_input : float | Sized Number or array to check. exact_length : int | VectorLike[int], optional Check if the array has the given length. If multiple numbers are given, the array's length must match one of the numbers. min_length : int, optional Check if the array has this length or greater. max_length : int, optional Check if the array has this length or less. must_be_1d : bool, default: False If ``True``, check if the shape of the array is one-dimensional, i.e. that the array's shape is ``(1,)``. allow_scalar : bool, default: False If ``True``, a scalar input will be reshaped to have a length of 1. Otherwise, the check will fail since a scalar does not have a length. name : str, default: "Array" Variable name to use in the error messages if any are raised. Raises ------ ValueError If the array's length is outside the specified range. See Also -------- check_shape check_ndim Examples -------- Check if an array has a length of 2 or 3. >>> from pyvista import _validation >>> _validation.check_length([1, 2], exact_length=[2, 3]) Check if an array has a minimum length of 3. >>> _validation.check_length((1, 2, 3), min_length=3) Check if a multidimensional array has a maximum length of 2. >>> _validation.check_length([[1, 2, 3], [4, 5, 6]], max_length=2) """ if allow_scalar: # Reshape to 1D if isinstance(sized_input, np.ndarray) and sized_input.ndim == 0: sized_input = [sized_input.tolist()] elif isinstance(sized_input, (float, int)): sized_input = [sized_input] if must_be_1d: check_shape(sized_input, shape=(-1)) # type: ignore[arg-type] array_len = len(sized_input) # type: ignore[arg-type] if exact_length is not None: check_integer(exact_length, name="'exact_length'") if array_len not in np.atleast_1d(exact_length): msg = ( f'{name} must have a length equal to any of: {exact_length}. ' f'Got length {array_len} instead.' ) raise ValueError(msg) # Validate min/max length if min_length is not None: check_finite(min_length, name='Min length') if max_length is not None: check_finite(max_length, name='Max length') if min_length is not None and max_length is not None: check_sorted((min_length, max_length), name='Range') if min_length is not None and array_len < min_length: msg = f'{name} must have a minimum length of {min_length}. Got length {array_len} instead.' raise ValueError(msg) if max_length is not None and array_len > max_length: msg = f'{name} must have a maximum length of {max_length}. Got length {array_len} instead.' raise ValueError(msg) def _validate_shape_value(shape: _ShapeLike) -> _Shape: """Validate shape-like input and return its tuple representation.""" if shape is None: # `None` is used to mean `any shape is allowed` by the array # validation methods, so raise an error here. # Also, setting `None` as a shape is deprecated by NumPy. msg = '`None` is not a valid shape. Use `()` instead.' # type: ignore[unreachable] raise TypeError(msg) # Return early for common inputs if shape in [(), (-1,), (1,), (3,), (2,), (1, 3), (-1, 3)]: return shape def _is_valid_dim(d: Any) -> bool: return isinstance(d, int) and d >= -1 if _is_valid_dim(shape): return (cast('int', shape),) if isinstance(shape, tuple) and all(map(_is_valid_dim, shape)): return shape # Input is not valid at this point. Use checks to raise an # appropriate error check_instance(shape, (int, tuple), name='Shape') if isinstance(shape, int): shape = (shape,) else: check_iterable_items(shape, int, name='Shape') check_greater_than(shape, -1, name='Shape', strict=False) msg = 'This line should not be reachable.' # pragma: no cover raise RuntimeError(msg) # pragma: no cover