valarray 0.4__py3-none-any.whl

valarray/numpy/validation_functions.py

@@ -0,0 +1,170 @@
+"""
+*import* `validate_array` **function**
+
+*import* `validate_dtype` **function**
+
+*import* `validate_shape` **function**
+
+*import* `validate_array_values` **function**
+
+*import* `validate_field_values` **function**
+"""
+
+from types import EllipsisType
+from typing import Any, Literal, Sequence, overload
+
+import numpy as np
+import numpy.typing as npt
+
+from valarray.core.errors_exceptions import (
+    IncorrectAxNumberError,
+    IncorrectAxSizesError,
+    IncorrectDTypeError,
+    InvalidArrayValuesError,
+    InvalidFieldValuesError,
+    ValidationError,
+    ValidationErrorList,
+)
+from valarray.core.validation_functions import validate_array as core_validate_array
+from valarray.core.validation_functions import (
+    validate_array_values as core_validate_array_values,
+)
+from valarray.core.validation_functions import validate_dtype as core_validate_dtype
+from valarray.core.validation_functions import (
+    validate_field_values as core_validate_field_values,
+)
+from valarray.core.validation_functions import validate_shape as core_validate_shape
+from valarray.core.validators import Validator
+
+from .array_type_adapter import NumpyArrayTypeAdapter
+from .axes_and_fields import AxesTuple
+from .types import AdvancedIndex, NumpyDTypeT
+from .validators import NumpyValidator
+
+
+def validate_dtype(
+    arr: npt.NDArray[Any], dtypelike: npt.DTypeLike | EllipsisType
+) -> ValidationErrorList[IncorrectDTypeError[npt.DTypeLike, np.dtype]]:
+    """Validate that numpy array has the correct dtype.
+
+    Args:
+        arr (npt.NDArray[Any]): Array to be validated.
+        dtypelike (npt.DTypeLike | EllipsisType): Expected datatype
+            (if `...` , do not validate).
+
+    Returns:
+        errs (ValidationErrorList[IncorrectDTypeError[npt.DTypeLike, np.dtype]]):
+            list containing a single dtype error or an empty list.
+
+    (introduced ***v0.1***, last_modified ***v0.4***)
+    """
+    return core_validate_dtype(arr, dtypelike, NumpyArrayTypeAdapter())
+
+
+validate_shape = core_validate_shape
+
+
+def validate_array_values(
+    arr: npt.NDArray[NumpyDTypeT],
+    validators: Sequence[NumpyValidator[NumpyDTypeT]],
+) -> ValidationErrorList[
+    InvalidArrayValuesError[npt.NDArray[NumpyDTypeT], AdvancedIndex]
+]:
+    """Validate numpy array with a sequence of validators applied to the whole array
+    and return potential errors.
+
+    Args:
+        arr (npt.NDArray[NumpyDTypeT]: Array to be validated.
+        validators (Sequence[NumpyValidator[NumpyDTypeT]]: Validators to apply.
+
+    Returns:
+        errs (ValidationErrorList[InvalidArrayValuesError[npt.NDArray[NumpyDTypeT], AdvancedIndex]]):
+            List containing at most 1 error per validator.
+
+    (introduced ***v0.3***, last_modified ***v0.4***)
+    """
+    return core_validate_array_values(arr, validators, NumpyArrayTypeAdapter())
+
+
+@overload
+def validate_field_values(
+    arr: npt.NDArray[NumpyDTypeT],
+    schema: AxesTuple[NumpyDTypeT] | EllipsisType,
+    check_shape: Literal[False] = False,
+) -> ValidationErrorList[
+    InvalidFieldValuesError[npt.NDArray[NumpyDTypeT], AdvancedIndex]
+]: ...
+
+
+@overload
+def validate_field_values(
+    arr: npt.NDArray[NumpyDTypeT],
+    schema: AxesTuple[NumpyDTypeT] | EllipsisType,
+    check_shape: Literal[True] = True,
+) -> (
+    ValidationErrorList[
+        InvalidFieldValuesError[npt.NDArray[NumpyDTypeT], AdvancedIndex]
+    ]
+    | ValidationErrorList[IncorrectAxNumberError | IncorrectAxSizesError]
+): ...
+
+
+def validate_field_values(
+    arr: npt.NDArray[NumpyDTypeT],
+    schema: AxesTuple[NumpyDTypeT] | EllipsisType,
+    check_shape: bool = False,
+) -> (
+    ValidationErrorList[
+        InvalidFieldValuesError[npt.NDArray[NumpyDTypeT], AdvancedIndex]
+    ]
+    | ValidationErrorList[IncorrectAxNumberError | IncorrectAxSizesError]
+):
+    """Validate numpy array fields with validators defined in schema and return potential errors.
+
+    Args:
+        arr (npt.NDArray[NumpyDTypeT]): Array to be validated.
+        schema (AxesTuple | EllipsisType):
+            Array schema (if `...` , do not validate).
+        check_shape (bool, optional): If `True`, check shape with `validate_shape()` first.
+            Defaults to False.
+
+    Returns:
+        errs (ValidationErrorList[InvalidFieldValuesError[npt.NDArray[NumpyDTypeT], AdvancedIndex]]):
+            List containing at most 1 error per validator
+            (including built-in field value comparisons like `gt`, `lt` etc.).
+
+    (introduced ***v0.4***)
+    """
+    return core_validate_field_values(arr, schema, NumpyArrayTypeAdapter(), check_shape)
+
+
+def validate_array(
+    arr: npt.NDArray[NumpyDTypeT],
+    dtypelike: npt.DTypeLike | EllipsisType,
+    schema: AxesTuple[NumpyDTypeT] | EllipsisType,
+    validators: Sequence[Validator[npt.NDArray[NumpyDTypeT], AdvancedIndex]],
+) -> ValidationErrorList[ValidationError]:
+    """Validate array:
+    - data type
+    - shape (based on array schema)
+    - array values (using a sequence of validators)
+    - field values (based on validators defined in array schema)
+
+    First validate data type and shape. If those are correct, validate field and array values.
+
+    Args:
+        arr (npt.NDArray[NumpyDTypeT]): Array to be validated.
+        dtypelike (npt.DTypeLike | EllipsisType,): Expected datatype (if `...` , do not validate).
+        schema (AxesTuple[NumpyDTypeT] | EllipsisType):
+            Expected array schema (if `...` , do not validate).
+        validators (Sequence[Validator[npt.NDArray[NumpyDTypeT], AdvancedIndex]]):
+            Validators to apply.
+
+    Returns:
+        ValidationErrorList[ValidationError]: Validation errors.
+
+    (introduced ***v0.4***)
+    """
+    return core_validate_array(
+        arr, dtypelike, schema, validators, NumpyArrayTypeAdapter()
+    )

valarray/numpy/validators.py

@@ -0,0 +1,35 @@
+from abc import abstractmethod
+from typing import Generic, Optional
+
+import numpy.typing as npt
+
+from valarray.core.validators import ValidationResult, Validator
+
+from .types import AdvancedIndex, NumpyDTypeT
+
+
+class NumpyValidator(
+    Validator[npt.NDArray[NumpyDTypeT], AdvancedIndex], Generic[NumpyDTypeT]
+):
+    """Base class for numpy array Validators.
+
+    Type variables:
+    - `NumpyDTypeT` - data type of array to be validated.
+
+    Subclasses need to implement:
+        **abstract method**
+        - `validate` -
+            Method to validate an array.
+
+    Subclasses can optionally implement:
+        **abstract method**
+        - `__str__` -
+            String representation of validator used in error messages.
+            If not implemented defalts to class name.
+
+    (introduced ***v0.3***)"""
+
+    @abstractmethod
+    def validate(
+        self, arr: npt.NDArray[NumpyDTypeT]
+    ) -> Optional[bool | ValidationResult[AdvancedIndex]]: ...