valarray 0.4__py3-none-any.whl

valarray/core/validation_functions/field_values/core.py

@@ -0,0 +1,106 @@
+from types import EllipsisType
+from typing import Any, Literal, overload
+
+from valarray.core.array_type_adapter import ArrayTypeAdapter
+from valarray.core.axes_and_fields import AxesTuple, AxisNameAndIdx, FieldNameAndIdx
+from valarray.core.errors_exceptions import (
+    IncorrectAxNumberError,
+    IncorrectAxSizesError,
+    InvalidFieldValuesError,
+    ValidationErrorList,
+)
+from valarray.core.types import ArrayIndicesT, ArrayT, ComparableValueT
+from valarray.core.validation_functions.shape import validate_shape
+
+from .utils import gather_validators, process_axis, resolve_schema
+
+
+@overload
+def validate_field_values(
+    arr: ArrayT,
+    schema: AxesTuple[ArrayT, ArrayIndicesT, ComparableValueT] | EllipsisType,
+    ata: ArrayTypeAdapter[ArrayT, Any, Any, ArrayIndicesT, ComparableValueT],
+    check_shape: Literal[False] = False,
+) -> ValidationErrorList[InvalidFieldValuesError[ArrayT, ArrayIndicesT]]: ...
+
+
+@overload
+def validate_field_values(
+    arr: ArrayT,
+    schema: AxesTuple[ArrayT, ArrayIndicesT, ComparableValueT] | EllipsisType,
+    ata: ArrayTypeAdapter[ArrayT, Any, Any, ArrayIndicesT, ComparableValueT],
+    check_shape: Literal[True] = True,
+) -> (
+    ValidationErrorList[InvalidFieldValuesError[ArrayT, ArrayIndicesT]]
+    | ValidationErrorList[IncorrectAxNumberError | IncorrectAxSizesError]
+): ...
+
+
+def validate_field_values(
+    arr: ArrayT,
+    schema: AxesTuple[ArrayT, ArrayIndicesT, ComparableValueT] | EllipsisType,
+    ata: ArrayTypeAdapter[ArrayT, Any, Any, ArrayIndicesT, ComparableValueT],
+    check_shape: bool = False,
+) -> (
+    ValidationErrorList[InvalidFieldValuesError[ArrayT, ArrayIndicesT]]
+    | ValidationErrorList[IncorrectAxNumberError | IncorrectAxSizesError]
+):
+    """Validate array fields with validators defined in schema and return potential errors.
+
+    Args:
+        arr (ArrayT): Array to be validated.
+        schema (AxesTuple | EllipsisType):
+            Array schema (if `...` , do not validate).
+        ata (ArrayTypeAdapter[ArrayT, Any, Any, ArrayIndicesT, Any]):
+            Adapter for specific array type.
+        check_shape (bool, optional): If `True`, check shape with `validate_shape()` first.
+            Defaults to False.
+
+    Returns:
+        errs (ValidationErrorList[InvalidFieldValuesError[ArrayT, ArrayIndicesT]]):
+            List containing at most 1 error per validator
+            (including built-in field value comparisons like `gt`, `lt` etc.).
+
+    (introduced ***v0.4***)
+    """
+
+    if check_shape:
+        shape_errs = validate_shape(arr, schema)
+        if shape_errs:
+            return shape_errs
+
+    errs: ValidationErrorList[InvalidFieldValuesError[ArrayT, ArrayIndicesT]] = (
+        ValidationErrorList([])
+    )
+
+    if schema == ...:
+        return errs
+
+    resolved_schema = resolve_schema(schema, ata.comparisons)
+
+    val_dict = gather_validators(resolved_schema)
+
+    for validator, axes_and_fields in val_dict.items():
+        invalid_values_dict: dict[AxisNameAndIdx, dict[FieldNameAndIdx, Any]] = {}
+        is_fail = False
+
+        # TODO: add indices of invalid values to error
+
+        for ax, fields in axes_and_fields.items():
+            status, invalid_values = process_axis(arr, validator, ax, fields, ata)
+
+            if status == "FAIL":
+                is_fail = True
+
+                if invalid_values is not None:
+                    invalid_values_dict[ax] = invalid_values
+
+        if is_fail:
+            invalid_vals = (
+                invalid_values_dict if len(invalid_values_dict.items()) > 0 else None
+            )
+            errs.append(
+                ata.errors.invalid_field_values(validator, invalid_values=invalid_vals)
+            )
+
+    return errs

valarray/core/validation_functions/field_values/types_and_data_structures.py

@@ -0,0 +1,90 @@
+from dataclasses import dataclass
+from typing import Generic, Sequence
+
+from valarray.core.axes_and_fields import AxisNameAndIdx, FieldNameAndIdx
+from valarray.core.types import ArrayIndicesT, ArrayT, ComparableValueT
+from valarray.core.validators import ComparisonValidator, Validator
+
+AnyValidator = (
+    Validator[ArrayT, ArrayIndicesT]
+    | ComparisonValidator[ArrayT, ArrayIndicesT, ComparableValueT]
+)
+
+
+@dataclass
+class _ResolvedField(Generic[ArrayT, ArrayIndicesT, ComparableValueT]):
+    """Field name and index + list of all validators (including `ComparisonValidator`s)
+
+    ### Example:
+    ```
+    _ResolvedField(
+        name_and_index=FieldNameAndIdx(name="example_field", idx=1),
+        validators=[
+            ComparisonValidator(operator="ge", value=1, comparisons=...),
+            ...
+        ],
+    )
+    ```
+    """
+
+    name_and_index: FieldNameAndIdx
+
+    validators: Sequence[AnyValidator]
+
+    def __str__(self) -> str:
+        val_list = [f"-> '{str(v)}': {repr(v)}" for v in self.validators]
+        val_s = "\n" + "\n".join(val_list) if val_list else " -> NA"
+        return str(self.name_and_index) + val_s
+
+
+@dataclass
+class _ResolvedAx(Generic[ArrayT, ArrayIndicesT, ComparableValueT]):
+    """Axis name and index + list of fields (name and index + list of all validators)
+
+    ### Example:
+    ```
+    _ResolvedAx(
+        name_and_index=AxisNameAndIdx("example_axis", idx=0),
+        fields=[
+            _ResolvedField(
+                name_and_index=FieldNameAndIdx(name="example_field_a", idx=0),
+                validators=[
+                    ComparisonValidator(
+                        operator="ge", value=1, comparisons=...
+                    ),
+                    ...
+                ],
+            ),
+            _ResolvedField(
+                name_and_index=FieldNameAndIdx(name="example_field", idx=1),
+                validators=[
+                    ComparisonValidator(
+                        operator="lt", value=100, comparisons=...
+                    ),
+                    ...
+                ],
+            ),
+        ],
+    )
+    ```
+    """
+
+    name_and_index: AxisNameAndIdx
+    fields: list[_ResolvedField[ArrayT, ArrayIndicesT, ComparableValueT]]
+
+    def __str__(self) -> str:
+        val_s = (
+            "\n\n" + "\n".join([str(f) for f in self.fields])
+            if self.fields
+            else " -> NA"
+        )
+        return str(self.name_and_index) + val_s
+
+
+_ResolvedAxesTuple = tuple[_ResolvedAx[ArrayT, ArrayIndicesT, ComparableValueT], ...]
+
+
+_FieldValidatorDict = dict[
+    AnyValidator[ArrayT, ArrayIndicesT, ComparableValueT],
+    dict[AxisNameAndIdx, list[FieldNameAndIdx]],
+]

valarray/core/validation_functions/field_values/utils.py

@@ -0,0 +1,143 @@
+from typing import Any, Literal
+
+from valarray.core.array_type_adapter import ArrayTypeAdapter
+from valarray.core.axes_and_fields import (
+    AxesTuple,
+    AxisNameAndIdx,
+    Field,
+    FieldNameAndIdx,
+)
+from valarray.core.comparisons import Comparisons
+from valarray.core.types import ArrayIndicesT, ArrayT, ComparableValueT
+from valarray.core.utils import constraints_to_validators
+from valarray.core.validation_functions.utils import apply_validator
+
+from .types_and_data_structures import (
+    AnyValidator,
+    _FieldValidatorDict,
+    _ResolvedAx,
+    _ResolvedAxesTuple,
+    _ResolvedField,
+)
+
+
+def _resolve_field(
+    i: int,
+    fld: str | Field[ArrayT, ArrayIndicesT, ComparableValueT],
+    comparisons: Comparisons[ArrayT, ArrayIndicesT, ComparableValueT],
+) -> _ResolvedField[ArrayT, ArrayIndicesT, ComparableValueT]:
+    """Get index, (optional) name and full list of validators for field.
+
+    ## Examples:
+    ```
+    _resolve_field(i=0, fld="field_string", comparisons=...)
+    >>> _ResolvedField(FieldNameAndIdx(name="field_string", idx=0), [])
+
+    _resolve_field(
+        i=0,
+        fld=Field(name="example_field", ge=0, validators=()),
+        comparisons=...,
+    )
+    >>> _ResolvedField(
+        FieldNameAndIdx(name="example_field", idx=0),
+        validators=[] + [ComparisonValidator(operator="ge", value=0, comparisons=...)],
+    )
+
+    _resolve_field(
+        i=0,
+        fld=Field(),
+        comparisons=NumpyComparisons(),
+    )
+    >>> _ResolvedField(FieldNameAndIdx(idx=0), validators=[])
+    ```
+    """
+    if isinstance(fld, str):
+        return _ResolvedField(FieldNameAndIdx(i, fld), [])
+
+    validators = constraints_to_validators(
+        fld.lt, fld.le, fld.ge, fld.gt, fld.eq, comparisons
+    ) + list(fld.validators)
+
+    return _ResolvedField(FieldNameAndIdx(i, fld.name), validators)
+
+
+def resolve_schema(
+    array_schema: AxesTuple[ArrayT, ArrayIndicesT, ComparableValueT],
+    comparisons: Comparisons[ArrayT, ArrayIndicesT, ComparableValueT],
+) -> _ResolvedAxesTuple[ArrayT, ArrayIndicesT, ComparableValueT]:
+    """Get name, index and list of field for each axis in schema.
+
+    ## Example:
+    ```
+    resolve_schema(
+        (16, "example_ax", ("example_field",)), TestComparisons()
+    )
+    >>> (
+        _ResolvedAx(AxisNameAndIdx(name="axis_0_len_16", idx=0), fields=[]),
+        _ResolvedAx(AxisNameAndIdx(name="example_ax", idx=1), fields=[]),
+        _ResolvedAx(
+            AxisNameAndIdx(name="axis_2_len_1", idx=2),
+            fields=[
+                _ResolvedField(FieldNameAndIdx("example_field", idx=0), validators=[])
+            ],
+        ),
+    )
+    ```
+    """
+    axes: list[_ResolvedAx[ArrayT, ArrayIndicesT, ComparableValueT]] = []
+
+    for ax_i, ax in enumerate(array_schema):
+        if isinstance(ax, str):
+            name = ax
+        else:
+            size = ax if isinstance(ax, int) else len(ax)
+            name = f"_sized_{size}"
+
+        if isinstance(ax, (str, int)):
+            fields = []
+        else:
+            fields = [_resolve_field(f_i, f, comparisons) for f_i, f in enumerate(ax)]
+
+        axes.append(_ResolvedAx(AxisNameAndIdx(ax_i, name), fields))
+
+    return tuple(axes)
+
+
+def gather_validators(
+    resolved_schema: _ResolvedAxesTuple[ArrayT, ArrayIndicesT, ComparableValueT],
+) -> _FieldValidatorDict[ArrayT, ArrayIndicesT, ComparableValueT]:
+    val_dict: _FieldValidatorDict[ArrayT, ArrayIndicesT, ComparableValueT] = {}
+
+    for ax in resolved_schema:
+        for fld in ax.fields:
+            for val in fld.validators:
+                if val_dict.get(val) is None:
+                    val_dict[val] = {}
+
+                if val_dict[val].get(ax.name_and_index) is None:
+                    val_dict[val][ax.name_and_index] = []
+
+                val_dict[val][ax.name_and_index].append(fld.name_and_index)
+
+    return val_dict
+
+
+def process_axis(
+    arr: ArrayT,
+    validator: AnyValidator[ArrayT, ArrayIndicesT, ComparableValueT],
+    ax: AxisNameAndIdx,
+    fields: list[FieldNameAndIdx],
+    ata: ArrayTypeAdapter[ArrayT, Any, Any, ArrayIndicesT, ComparableValueT],
+) -> tuple[Literal["FAIL", "OK"], dict[FieldNameAndIdx, Any] | None]:
+    arr_subset = ata.select_subset(arr, ax, fields)
+
+    res = apply_validator(validator, arr_subset)
+
+    if res.status == "FAIL":
+        invalid_values = ata.get_values_from_subset(
+            arr_subset, res.indices_invalid, ax, fields
+        )
+    else:
+        invalid_values = None
+
+    return res.status, invalid_values

valarray/core/validation_functions/shape.py

@@ -0,0 +1,67 @@
+from dataclasses import dataclass
+from types import EllipsisType
+from typing import Any, Optional
+
+from valarray.core.axes_and_fields import AxesTuple
+from valarray.core.errors_exceptions import (
+    IncorrectAxNumberError,
+    IncorrectAxSizesError,
+    ValidationErrorList,
+)
+from valarray.core.types import ArrayP
+from valarray.core.utils import ax_sizes_from_schema
+
+
+@dataclass
+class _AxComp:
+    actual: int
+    expected: Optional[int]
+
+
+def validate_shape(
+    arr: ArrayP,
+    schema: AxesTuple[Any, Any, Any] | EllipsisType,
+) -> ValidationErrorList[IncorrectAxNumberError | IncorrectAxSizesError]:
+    """Validate that array has the correct shape.
+
+    Args:
+        arr (ArrayT): Array to be validated.
+        schema (AxesTuple | EllipsisType):
+            Expected array schema (if `...` , do not validate).
+
+    Returns:
+        errs (ValidationErrorList[IncorrectAxNumberError | IncorrectAxSizesError]):
+            incorrect ax number error and/or incorrect ax sizes error
+
+    (introduced ***v0.2***, last_modified ***v0.4***)
+    """
+    errs: ValidationErrorList[IncorrectAxNumberError | IncorrectAxSizesError] = (
+        ValidationErrorList([])
+    )
+
+    if schema == ...:
+        return errs
+
+    ax_sizes = ax_sizes_from_schema(schema)
+
+    n_ax_actual = len(arr.shape)
+    n_ax_expected = len(ax_sizes)
+    if n_ax_actual != n_ax_expected:
+        errs.append(IncorrectAxNumberError(n_ax_actual, n_ax_expected))
+
+    min_n_ax = min(n_ax_actual, n_ax_expected)
+
+    incorrect_indices: list[int] = []
+    for i, ax in enumerate(
+        [_AxComp(a, e) for a, e in zip(arr.shape[:min_n_ax], ax_sizes[:min_n_ax])]
+    ):
+        if ax.expected is None:
+            continue
+
+        if ax.actual not in (ax.expected, 0):
+            incorrect_indices.append(i)
+
+    if incorrect_indices:
+        errs.append(IncorrectAxSizesError(arr.shape, ax_sizes, incorrect_indices))
+
+    return errs

valarray/core/validation_functions/utils.py

@@ -0,0 +1,24 @@
+from valarray.core.types import ArrayIndicesT, ArrayT
+from valarray.core.validators.base import ValidationResult, Validator
+
+
+def apply_validator(
+    validator: Validator[ArrayT, ArrayIndicesT], arr: ArrayT
+) -> ValidationResult[ArrayIndicesT]:
+    """Call `validator.validate()` method on array, catch `ValueError` and return `ValidationResult`
+
+    (introduced ***v0.3***)
+    """
+    try:
+        res_or_bool_or_none = validator.validate(arr)
+
+        if isinstance(res_or_bool_or_none, ValidationResult):
+            res = res_or_bool_or_none
+        elif res_or_bool_or_none in (None, True):
+            res = ValidationResult("OK")
+        else:
+            res = ValidationResult("FAIL")
+    except ValueError as val_err:
+        res = ValidationResult("FAIL", msg=str(val_err))
+
+    return res

valarray/core/validators/__init__.py

@@ -0,0 +1,13 @@
+"""
+*import* `Validator` **ABC**
+
+*import* `ValidationResult` **dataclass**
+
+*import* `ComparisonValidator` **Validator**
+"""
+
+# pyright: reportUnusedImport=false
+
+# NOTE: Wanted Validator to be imported from 'valarray.core', but that caused circular imports.
+from .base import ValidationResult, Validator
+from .value_comparisons import ComparisonValidator

valarray/core/validators/base.py

@@ -0,0 +1,72 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Generic, Literal, Optional
+
+from valarray.core.types import ArrayIndicesT, ArrayT
+
+
+@dataclass
+class ValidationResult(Generic[ArrayIndicesT]):
+    """Result of `Validator.validate()` method.
+
+    Attributes:
+        status(Literal["OK", "FAIL"]): Whether validation is succesfull (`OK`) or not (`FAIL`).
+        indices_invalid(Optional[ArrayIndicesT]):
+            Optional indices of values that failed validation. Defaults to None.
+        msg (Optional[str]): Optional message to be added to
+            `valarray.core.errors_exceptions.InvalidArrayValuesError`.
+            Defaults to None.
+
+    (introduced ***v0.3***)
+    """
+
+    status: Literal["OK", "FAIL"]
+    indices_invalid: Optional[ArrayIndicesT] = None
+    msg: Optional[str] = None
+
+
+class Validator(ABC, Generic[ArrayT, ArrayIndicesT]):
+    """Generic validator base class.
+
+    Type variables:
+        - `ArrayT` - type of array object
+        - `ArrayIndexT` - object(s) that can select values from array using `__getitem__` method.
+
+    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 defaults to class name.
+
+    (introduced ***v0.3***)
+    """
+
+    @abstractmethod
+    def validate(
+        self, arr: ArrayT
+    ) -> Optional[bool | ValidationResult[ArrayIndicesT]]: ...
+
+    def __str__(self) -> str:
+        return self.__class__.__name__
+
+    # HACK: This nonsense should ensure that every subclass has a hash method that
+    # returns hash created from instance attributes after initialization and class name
+    def __post_init__(self):
+        cls_name = self.__class__.__name__
+        name_hash = int.from_bytes(
+            cls_name.encode("utf-8"), byteorder="big", signed=False
+        )
+
+        # NOTE: hash of vars().values() is not deterministic, but converted to tuple it is
+        attr_hash = hash(tuple(vars(self).values()))
+
+        self.__hash = name_hash + attr_hash  # pylint:disable=W0201
+        self.__class__.__hash__ = Validator.__hash__
+
+    def __hash__(self) -> int:
+        return self.__hash

valarray/core/validators/value_comparisons.py

@@ -0,0 +1,107 @@
+from dataclasses import dataclass
+from typing import Generic
+
+from valarray.core.comparisons import Comparisons
+from valarray.core.types import (
+    ArrayIndicesT,
+    ArrayT,
+    ComparableValueT,
+    ComparisonOperator,
+)
+
+from .base import ValidationResult, Validator
+
+
+def _get_comparison(
+    operator: ComparisonOperator,
+    comparisons: Comparisons[ArrayT, ArrayIndicesT, ComparableValueT],
+):
+    lookup = {
+        "lt": comparisons.where_not_lt,
+        "le": comparisons.where_not_le,
+        "ge": comparisons.where_not_ge,
+        "gt": comparisons.where_not_gt,
+        "eq": comparisons.where_not_eq,
+    }
+
+    op = lookup.get(operator)
+
+    if op is None:
+        raise NotImplementedError
+
+    return op
+
+
+# NOTE: One day I will learn why pylance yells at me if
+# ArrayT, ArrayIndicesT are not in both Validator AND Generic
+@dataclass
+class ComparisonValidator(
+    Validator[ArrayT, ArrayIndicesT], Generic[ArrayT, ArrayIndicesT, ComparableValueT]
+):
+    """Validator that compares array with a value
+
+    Attributes:
+        operator (ComparisonOperator): ***"lt"***/***"le"***/***"ge"***/***"gt"***/***"eq"***/
+        value (ComparableValueT): Value to compare with. Dependent on array type.
+        comparisons (Comparisons[ArrayT, ArrayIndicesT, ComparableValueT]):
+            Array type implementation of `Comparisons()` object.
+
+    (introduced ***v0.3***)"""
+
+    operator: ComparisonOperator
+    value: ComparableValueT
+    comparisons: Comparisons[ArrayT, ArrayIndicesT, ComparableValueT]
+
+    def validate(self, arr) -> ValidationResult[ArrayIndicesT]:
+        """Validate that array values conform to specified constraints.
+
+        Args:
+            arr (ArrayT): Array to validate.
+
+        Returns:
+            ValidationResult[ArrayIndicesT]: Result of validation,
+                plus indices of invalid values if validation is unsuccessfull.
+
+        (introduced ***v0.3***)
+        """
+        comp = _get_comparison(self.operator, self.comparisons)
+
+        indices_invalid = comp(arr, self.value)
+
+        n_invalid = self.comparisons.n_indices(indices_invalid)
+
+        return ValidationResult(
+            status=("FAIL" if n_invalid > 0 else "OK"),
+            indices_invalid=indices_invalid if n_invalid > 0 else None,
+        )
+
+    def __str__(self) -> str:
+        """String representation of validator.
+
+        ### Examples:
+        ```
+        comp_val = ComparisonValidator(operator="gt", value=3, ...)
+        >>> str(comp_val)
+        >>> '> 3'
+
+        comp_val = ComparisonValidator(operator="eq", value=2.4, ...)
+        >>> str(comp_val)
+        >>> '== 2.4'
+        ```
+
+        (introduced ***v0.3***, last_modified ***v0.4***)
+        """
+        # NOTE: opposite operator, because the message makes more sense to me:
+        # eg: Invalid * values (<= 0): [-1, -2]
+        # instead of: Invalid * values (> 0): [-1, -2]
+        lookup: dict[ComparisonOperator, str] = {
+            "lt": ">=",
+            "le": ">",
+            "ge": "<",
+            "gt": "<=",
+            "eq": "!=",
+        }
+
+        op = lookup[self.operator]
+
+        return f"{op} {self.value}"

valarray/numpy/__init__.py

@@ -0,0 +1,24 @@
+"""
+*import* `ValidatedNumpyArray` **ValidatedArray**
+
+*import* `NumpyArrayTypeAdapter` **ArrayTypeAdapter**
+
+*import* `NumpyComparisons` **Comparisons**
+
+*import* `Field` **dataclass**
+
+*import* `NumpyValidator` **ABC/Validator**
+
+`.types` ***module***
+
+`.validation_functions` ***module***
+
+`.errors_exceptions` ***module***
+"""
+
+# pyright: reportUnusedImport=false
+from .array import ValidatedNumpyArray
+from .array_type_adapter import NumpyArrayTypeAdapter
+from .axes_and_fields import Field
+from .comparisons import NumpyComparisons
+from .validators import NumpyValidator