valarray 0.4__py3-none-any.whl

valarray/core/errors_exceptions/generic.py

@@ -0,0 +1,57 @@
+from abc import ABC
+from dataclasses import dataclass
+from typing import Generic
+
+from valarray.core.types import ArrayIndicesT, ArrayT, DTypeLikeT, DTypeT
+
+from .validation_errors.dtype import CannotCoerceDTypeError, IncorrectDTypeError
+from .validation_errors.values import InvalidArrayValuesError, InvalidFieldValuesError
+
+
+@dataclass
+class GenericErrors(ABC, Generic[ArrayT, DTypeLikeT, DTypeT, ArrayIndicesT]):
+    """Generic `ValidationError` classes to be used in `ArrayTypeAdapter`.
+    Subclass these for each array type with specific types and assign them to
+    a 'GenericErrors' subclass.
+
+    ## Example:
+    ```
+    class ChildIncorrectDTypeError(IncorrectDTypeError[DTypeLike, Dtype]): ...
+
+    @dataclass
+    class ChildErrors(GenericErrors[DTypeLike, Dtype]):
+        incorrect_dtype: type[ChildIncorrectDTypeError] = ChildIncorrectDTypeError
+
+    ```
+
+    Necessary for correct type inference of errors accessed through a raised `ValidationException`.
+
+    ### Good:
+    ```
+    try:
+        ...
+    except ValidationException as exc:
+        for err in exc.errs:
+            if isinstance(err, ChildIncorrectDTypeError):
+                # dtypes => Dtype, DTypeLike
+                print(err.actual_dtype, err.expected_dtypelike)
+    ```
+
+    ### Bad:
+    ```
+    try:
+        ...
+    except ValidationException as exc:
+        for err in exc.errs:
+            if isinstance(err, IncorrectDTypeError):
+                # dtypes => Unknown
+                print(err.actual_dtype, err.expected_dtypelike)
+    ```
+
+    (introduced ***v0.2.4***)
+    """
+
+    incorrect_dtype: type[IncorrectDTypeError[DTypeLikeT, DTypeT]]
+    cannot_coerce_dtype: type[CannotCoerceDTypeError[DTypeLikeT, DTypeT]]
+    invalid_array_values: type[InvalidArrayValuesError[ArrayT, ArrayIndicesT]]
+    invalid_field_values: type[InvalidFieldValuesError[ArrayT, ArrayIndicesT]]

valarray/core/errors_exceptions/validation_errors/array_creation.py

@@ -0,0 +1,14 @@
+from .base import ValidationError
+
+
+# [?] What information should this error contain, if any?
+class CannotCreateArrayError(ValidationError):
+    """Error caused by array type adapter not being able to create an array of specified data type
+    from supplied object.
+
+    (introduced ***v0.1***)
+    """
+
+    @property
+    def msg(self) -> str:
+        return "Cannot create array."

valarray/core/errors_exceptions/validation_errors/axes.py

@@ -0,0 +1,68 @@
+from dataclasses import dataclass
+
+from valarray.core.types import AxSizes
+
+from .base import ValidationError
+
+
+@dataclass
+class IncorrectAxNumberError(ValidationError):
+    """***Validation error:*** Array has incorrect number of axes.
+
+    Attributes:
+        actual_axis_number (int): Number of axes of the actual array.
+        expected_axis_number (int): Number of axes inferred from schema.
+
+    (introduced ***v0.2***)
+    """
+
+    actual_axis_number: int
+    expected_axis_number: int
+
+    @property
+    def msg(self) -> str:
+        act = self.actual_axis_number
+        exp = self.expected_axis_number
+        return f"Incorrect number of axes: {act}, expected {exp}."
+
+
+@dataclass
+class IncorrectAxSizesError(ValidationError):
+    """***Validation error:*** Array has ax(es) with incorrect size(s).
+
+    Attributes:
+        actual_sizes (tuple[int, ...]): Ax sizes of the actual array.
+        expected_sizes (AxSizes):
+            Expected ax sizes (or None for variable sized axis) inferred from schema.
+        incorrect_size_indices (list[int]): Indices of which axes have incorrect sizes.
+
+    Examples:
+    ```
+    err = IncorrectAxSizesError(
+        (1, 2, 3, 4), [2, None, 1, 4], incorrect_size_indices=[0, 2]
+    ),
+    print(err.msg)
+    >>> "Incorrect axis sizes: (*1*, 2, *3*, 4), expected (2, any, 1, 4)."
+    ```
+
+    (introduced ***v0.2***, last_modified ***v0.3***)
+    """
+
+    actual_sizes: tuple[int, ...]
+    expected_sizes: AxSizes
+    incorrect_size_indices: list[int]
+
+    @property
+    def msg(self) -> str:
+        act_sizes_str_list = [
+            f"*{s}*" if i in self.incorrect_size_indices else str(s)
+            for i, s in enumerate(self.actual_sizes)
+        ]
+        act_size_str = "(" + ", ".join(act_sizes_str_list) + ")"
+
+        exp_sizes_str_list = [
+            str(a) if a is not None else "any" for a in self.expected_sizes
+        ]
+        exp_size_str = "(" + ", ".join(exp_sizes_str_list) + ")"
+
+        return f"Incorrect axis sizes: {act_size_str}, expected {exp_size_str}."

valarray/core/errors_exceptions/validation_errors/base.py

@@ -0,0 +1,26 @@
+from abc import ABC, abstractmethod
+from typing import TypeVar
+
+
+class ValidationError(ABC):
+    """Base validation error. Subclasses need to implement:
+
+    **abstract property**
+    - `msg` -
+        Human readeble description of error.
+
+    (introduced ***v0.1***)
+    """
+
+    @property
+    @abstractmethod
+    def msg(self) -> str: ...
+
+
+ValidationErrorT = TypeVar("ValidationErrorT", bound=ValidationError)
+"""Validation error types contained in the error list.
+(introduced ***v0.4***)"""
+
+SelectedValidationErrorT = TypeVar("SelectedValidationErrorT", bound=ValidationError)
+"""Validation error types to be selected from the error list.
+(introduced ***v0.4***)"""

valarray/core/errors_exceptions/validation_errors/dtype.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass
+from typing import Generic
+
+from valarray.core.types import DTypeLikeT, DTypeT
+
+from .base import ValidationError
+
+
+def _dtype_str(dtype, dtypelike):
+    """`"dtype"`` OR `"dtypelike (dtype)"``"""
+    return str(dtype) if dtype == dtypelike else f"{dtypelike} ({dtype})"
+
+
+@dataclass
+class IncorrectDTypeError(ValidationError, Generic[DTypeLikeT, DTypeT]):
+    """***Validation error:*** Array has the wrong data type.
+
+    Attributes:
+        actual_dtype (DTypeT): Data type of the actual array.
+        expected_dtype (DTypeT): Expected data type (as a data type object).
+        expected_dtypelike (DTypeLikeT):
+            Expected data type specification from `ValidatedArray.dtype`.
+
+    (introduced ***v0.1***, last_modified ***v0.2.4***)
+    """
+
+    actual_dtype: DTypeT
+    expected_dtype: DTypeT
+    expected_dtypelike: DTypeLikeT
+
+    @property
+    def msg(self) -> str:
+        e = _dtype_str(self.expected_dtype, self.expected_dtypelike)
+
+        return f"Incorrect DType: '{self.actual_dtype}', expected '{e}'."
+
+
+@dataclass
+class CannotCoerceDTypeError(ValidationError, Generic[DTypeLikeT, DTypeT]):
+    """***Validation error:*** Array type adapter is not able to convert an existing array
+    to specified data type when creating an instance of ValidatedArray.
+
+    Attributes:
+        actual_dtype (DTypeT): Data type of array passed to `ValidatedArray.__init__`.
+        target_dtype (DTypeT): Data type to convert to (as a data type object).
+        target_dtypelike (DTypeLikeT):
+            Expected data type specification from `ValidatedArray.dtype`.
+
+    (introduced ***v0.1***, last_modified ***v0.2.4***)
+    """
+
+    actual_dtype: DTypeT
+    target_dtype: DTypeT
+    target_dtypelike: DTypeLikeT
+
+    @property
+    def msg(self) -> str:
+        e = _dtype_str(self.target_dtype, self.target_dtypelike)
+
+        return f"Cannot coerce data type from: '{self.actual_dtype}' to '{e}'."

valarray/core/errors_exceptions/validation_errors/values.py

@@ -0,0 +1,99 @@
+from dataclasses import dataclass
+from typing import Any, Generic, Optional
+
+from valarray.core.axes_and_fields import AxisNameAndIdx, FieldNameAndIdx
+from valarray.core.types import ArrayIndicesT, ArrayT
+from valarray.core.validators.base import Validator
+
+from .base import ValidationError
+
+
+@dataclass
+class _InvalidValuesError(ValidationError, Generic[ArrayT, ArrayIndicesT]):
+    validator: Validator[ArrayT, ArrayIndicesT]
+    # TODO: add extra
+
+
+@dataclass
+class InvalidArrayValuesError(_InvalidValuesError[ArrayT, ArrayIndicesT]):
+    """***ValidationError:*** Array has wrong values.
+
+    Attributes:
+        validator: (Validator[ArrayT, ArrayIndicesT]): Validator applied to the whole array.
+        invalid_values (Optional[list[Any]]):
+            Values causing the validation to fail. Defaults to None.
+        invalid_indices (Optional[ArrayIndicesT]): Indices of invalid values.
+        result_msg (Optional[str]): Optional message returned by validator.
+
+    (introduced ***v0.3***, last_modified ***v0.4***)
+    """
+
+    invalid_values: Optional[list[Any]] = None
+    invalid_indices: Optional[ArrayIndicesT] = None
+    result_msg: Optional[str] = None
+
+    @property
+    def msg(self) -> str:
+        validator_desc = str(self.validator)
+
+        header = f"Invalid Array Values ({validator_desc})"
+
+        if self.invalid_values is None and self.result_msg is None:
+            return f"{header}."
+
+        lines = []
+
+        if self.invalid_values is not None:
+            lines.append(f"\t{self.invalid_values}")
+
+        if self.result_msg is not None:
+            lines.append(f"\t{self.result_msg}")
+
+        return header + ":\n" + "\n".join(lines)
+
+
+type InvalidFieldValues = dict[AxisNameAndIdx, dict[FieldNameAndIdx, Any]]
+
+
+def _invalid_field_values_to_lines(ifv: InvalidFieldValues) -> list[str]:
+    lines: list[str] = []
+    for ax, fld_dict in ifv.items():
+        ax_name_str = f": '{ax.name}'" if ax.name is not None else ""
+
+        lines.append(f"\tAxis < {ax.idx} >{ax_name_str}")
+
+        for fld, invalid_values in fld_dict.items():
+            fld_name_str = f": '{fld.name}'" if fld.name is not None else ""
+            lines.append(f"\t\tField < {fld.idx} >{fld_name_str}: {invalid_values}")
+
+    return lines
+
+
+@dataclass
+class InvalidFieldValuesError(_InvalidValuesError[ArrayT, ArrayIndicesT]):
+    """***ValidationError:*** Field or fields have wrong values.
+
+    Attributes:
+        validator: (Validator[ArrayT, ArrayIndicesT]): Validator applied to array field(s).
+        invalid_values (Optional[InvalidFieldValues]):
+            Values causing the validation to fail, organized by axis and field. Defaults to None.
+
+    (introduced ***v0.4***)
+    """
+
+    invalid_values: Optional[InvalidFieldValues] = None
+
+    @property
+    def msg(self) -> str:
+        validator_desc = str(self.validator)
+
+        header = f"Invalid Field Values ({validator_desc})"
+
+        if self.invalid_values is None:
+            return f"{header}."
+
+        lines = []
+
+        lines.extend(_invalid_field_values_to_lines(self.invalid_values))
+
+        return header + ":\n" + "\n".join(lines)

valarray/core/types/__init__.py

@@ -0,0 +1,24 @@
+"""
+## Generics
+*import* `DTypeLikeT` **TypeVar**
+
+*import* `DTypeT` **TypeVar**
+
+*import* `ArrayT` **TypeVar**
+
+*import* `ArrayIndicesT` **TypeVar**
+
+*import* `ComparableValueT` **TypeVar**
+
+## Other
+*import* `ArrayP` **Protocol**
+
+*import* `ComparisonOperator` **type**
+
+*import* `AxSizes` **type**
+"""
+
+from .generics import ArrayIndicesT, ArrayT, ComparableValueT, DTypeLikeT, DTypeT
+from .other import ArrayP, AxSizes, ComparisonOperator
+
+# pyright: reportUnusedImport=false

valarray/core/types/generics.py

@@ -0,0 +1,40 @@
+from typing import TypeVar
+
+from .other import ArrayP
+
+# NOTE: using old-school generics because I'm not familiar with the new syntax
+# and I don't know how to customize syntax highligting for it in VSCode.
+
+
+DTypeLikeT = TypeVar("DTypeLikeT")
+"""Data type object or object that can be used to construct a data type object.
+```
+dtypelike = "float32"
+dtypelike = float
+dtypelike = Float32()
+
+dt = dtype(dtypelike)
+dt == Float32()
+>>> True
+```
+
+(introduced ***v0.1***)
+"""
+
+DTypeT = TypeVar("DTypeT")
+"""(introduced ***v0.1***)"""
+
+
+ArrayT = TypeVar("ArrayT", bound=ArrayP)
+"""Generic array object conforming to `ArrayP` protocol.
+(introduced ***v0.1***)"""
+
+ArrayIndicesT = TypeVar("ArrayIndicesT")
+"""Object that can select values from array using `__getitem__` method.
+(introduced ***v0.3***)
+"""
+
+ComparableValueT = TypeVar("ComparableValueT")
+"""Value or object an array can be compared with using `<`, `<=`, `==`, `=>`, `>` operators.
+(introduced ***v0.3***)
+"""

valarray/core/types/other.py

@@ -0,0 +1,23 @@
+from collections.abc import Sequence
+from typing import Any, Literal, Protocol
+
+
+class ArrayP(Protocol):
+    """(introduced ***v0.1***, last_modified ***v0.2***)"""
+
+    @property
+    def dtype(self) -> Any: ...
+
+    @property
+    def shape(self) -> tuple[int, ...]: ...
+
+
+type ComparisonOperator = Literal["lt", "le", "ge", "gt", "eq"]
+"""(introduced ***v0.3***)"""
+
+
+type AxSizes = Sequence[int | None]
+"""Array sizes from schema or 'None' if unknown.
+
+(introduced ***v0.1.1***, last_modified ***v0.4***)
+"""

valarray/core/utils.py

@@ -0,0 +1,89 @@
+"""
+*import* `setup_array` **function**
+"""
+
+from types import EllipsisType
+from typing import Any, Optional
+
+from .array_type_adapter import ArrayTypeAdapter
+from .axes_and_fields import AxesTuple
+from .comparisons import Comparisons
+from .errors_exceptions import CoerceDTypeException, CreateArrayException
+from .types import ArrayIndicesT, ArrayT, AxSizes, ComparableValueT, DTypeLikeT
+from .validators import ComparisonValidator
+
+
+def ax_sizes_from_schema(schema: AxesTuple[Any, Any, Any]) -> AxSizes:
+    """(introduced ***v0.1.1***)"""
+    sizes: AxSizes = []
+
+    for ax in schema:
+        if isinstance(ax, int):
+            sizes.append(ax)
+        elif isinstance(ax, str):
+            sizes.append(None)
+        else:
+            sizes.append(len(ax))
+
+    return sizes
+
+
+def constraints_to_validators(
+    lt: Optional[ComparableValueT],
+    le: Optional[ComparableValueT],
+    ge: Optional[ComparableValueT],
+    gt: Optional[ComparableValueT],
+    eq: Optional[ComparableValueT],
+    comparisons: Comparisons[ArrayT, ArrayIndicesT, ComparableValueT],
+) -> list[ComparisonValidator[ArrayT, ArrayIndicesT, ComparableValueT]]:
+    """(introduced ***v0.3***)"""
+    validators = []
+
+    for val, operator in zip((lt, le, ge, gt, eq), ("lt", "le", "ge", "gt", "eq")):
+        if val is not None:
+            validators.append(ComparisonValidator(operator, val, comparisons))
+
+    return validators
+
+
+def setup_array(
+    obj: Any,
+    dtypelike: DTypeLikeT | EllipsisType,
+    coerce_dtype: Optional[bool],
+    schema: AxesTuple[Any, Any, Any] | EllipsisType,
+    ata: ArrayTypeAdapter[ArrayT, DTypeLikeT, Any, Any, Any],
+    cls_name: str,
+) -> ArrayT:
+    """Creates array if it already doesn't exist. Speciffically if:
+    - `obj` is an array AND
+        - `coerce_dtype` is `False` OR `dtypelike == ...` -> return `obj`
+        - `coerce_dtype` is `True` -> try to convert dtype,
+            throw `CannotCoerceDTypeException` on fail.
+    - `obj` is `None` -> create an empty array
+    - `obj` is any other object -> try to create array, throw `CreateArrayException` on fail.
+
+    (introduced ***v0.1***, last_modified ***v0.2.4***)
+    """
+    if isinstance(obj, ata.array_type):
+        if coerce_dtype is False or dtypelike == ...:
+            arr = obj
+        else:
+            try:
+                arr = ata.change_dtype(obj, dtypelike)
+            except Exception as exc:
+                raise CoerceDTypeException(
+                    cls_name,
+                    ata.errors.cannot_coerce_dtype(
+                        obj.dtype, ata.dtype_from_dtypelike(dtypelike), dtypelike
+                    ),
+                ) from exc
+    elif obj is None:
+        ax_sizes = ax_sizes_from_schema(schema if schema != ... else tuple())
+        arr = ata.create_empty_array(ax_sizes, dtypelike)
+    else:
+        try:
+            arr = ata.create_array(obj, dtypelike)
+        except Exception as exc:
+            raise CreateArrayException(cls_name) from exc
+
+    return arr

valarray/core/validation_functions/__init__.py

@@ -0,0 +1,20 @@
+"""
+*import* `validate_array` **function**
+
+*import* `validate_dtype` **function**
+
+*import* `validate_shape` **function**
+
+*import* `validate_array_values` **function**
+
+*import* `validate_field_values` **function**
+
+`.utils` ***module***
+"""
+
+# pyright: reportUnusedImport=false
+from .array import validate_array
+from .array_values import validate_array_values
+from .dtype import validate_dtype
+from .field_values.core import validate_field_values
+from .shape import validate_shape

valarray/core/validation_functions/array.py

@@ -0,0 +1,62 @@
+from collections.abc import Sequence
+from types import EllipsisType
+from typing import Any
+
+from valarray.core.array_type_adapter import ArrayTypeAdapter
+from valarray.core.axes_and_fields import AxesTuple
+from valarray.core.errors_exceptions import ValidationError, ValidationErrorList
+from valarray.core.types import (
+    ArrayIndicesT,
+    ArrayT,
+    ComparableValueT,
+    DTypeLikeT,
+    DTypeT,
+)
+from valarray.core.validators import Validator
+
+from .array_values import validate_array_values
+from .dtype import validate_dtype
+from .field_values.core import validate_field_values
+from .shape import validate_shape
+
+
+def validate_array(
+    arr: ArrayT,
+    dtypelike: DTypeLikeT | EllipsisType,
+    schema: AxesTuple[Any, Any, Any] | EllipsisType,
+    validators: Sequence[Validator[ArrayT, ArrayIndicesT]],
+    ata: ArrayTypeAdapter[ArrayT, DTypeLikeT, DTypeT, ArrayIndicesT, ComparableValueT],
+) -> 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 (ArrayT): Array to be validated.
+        dtypelike (DTypeLikeT | EllipsisType): Expected datatype (if `...` , do not validate).
+        schema (AxesTuple | EllipsisType): Expected array schema (if `...` , do not validate).
+        validators (Sequence[Validator[ArrayT]]): Validators to apply.
+        ata (ArrayTypeAdapter[ArrayT, DTypeLikeT, DTypeT, ArrayIndicesT, ComparableValueT]):
+            Adapter for specific array type.
+
+    Returns:
+        ValidationErrorList[ValidationError]: Validation errors.
+
+    (introduced ***v0.4***)
+    """
+    errs: ValidationErrorList[ValidationError] = ValidationErrorList([])
+
+    errs += validate_dtype(arr, dtypelike, ata)
+    errs += validate_shape(arr, schema)
+
+    if errs:
+        return errs
+
+    errs += validate_array_values(arr, validators, ata)
+    errs += validate_field_values(arr, schema, ata)
+
+    return errs

valarray/core/validation_functions/array_values.py

@@ -0,0 +1,47 @@
+from collections.abc import Sequence
+from typing import Any
+
+from valarray.core.array_type_adapter import ArrayTypeAdapter
+from valarray.core.errors_exceptions import InvalidArrayValuesError, ValidationErrorList
+from valarray.core.types import ArrayIndicesT, ArrayT
+from valarray.core.validation_functions.utils import apply_validator
+from valarray.core.validators.base import Validator
+
+
+def validate_array_values(
+    arr: ArrayT,
+    validators: Sequence[Validator[ArrayT, ArrayIndicesT]],
+    ata: ArrayTypeAdapter[ArrayT, Any, Any, ArrayIndicesT, Any],
+) -> ValidationErrorList[InvalidArrayValuesError[ArrayT, ArrayIndicesT]]:
+    """Validate array with a sequence of validators applied to the whole array
+    and return potential errors.
+
+    Args:
+        arr (ArrayT): Array to be validated.
+        validators (Sequence[Validator[ArrayT]]): Validators to apply.
+        ata (ArrayTypeAdapter[ArrayT, Any, Any, ArrayIndicesT, Any]):
+            Adapter for specific array type.
+
+    Returns:
+        errs (ValidationErrorList[InvalidArrayValuesError[ArrayT, ArrayIndicesT]]):
+            List containing at most 1 error per validator.
+
+    (introduced ***v0.3***, last_modified ***v0.4***)
+    """
+    errs: ValidationErrorList[InvalidArrayValuesError[ArrayT, ArrayIndicesT]] = (
+        ValidationErrorList([])
+    )
+
+    for validator in validators:
+        res = apply_validator(validator, arr)
+
+        if res.status == "FAIL":
+            invalid_values = ata.get_values(arr, res.indices_invalid)
+
+            errs.append(
+                ata.errors.invalid_array_values(
+                    validator, invalid_values, res.indices_invalid, res.msg
+                )
+            )
+
+    return errs

valarray/core/validation_functions/dtype.py

@@ -0,0 +1,44 @@
+from types import EllipsisType
+from typing import Any
+
+from valarray.core.array_type_adapter import ArrayTypeAdapter
+from valarray.core.errors_exceptions import IncorrectDTypeError, ValidationErrorList
+from valarray.core.types import ArrayT, DTypeLikeT, DTypeT
+
+
+def validate_dtype(
+    arr: ArrayT,
+    dtypelike: DTypeLikeT | EllipsisType,
+    ata: ArrayTypeAdapter[ArrayT, DTypeLikeT, DTypeT, Any, Any],
+) -> ValidationErrorList[IncorrectDTypeError[DTypeLikeT, DTypeT]]:
+    """Validate that array has the correct dtype.
+
+    Args:
+        arr (ArrayT): Array to be validated.
+        dtypelike (DTypeLikeT | EllipsisType): Expected datatype (if `...` , do not validate).
+        ata (ArrayTypeAdapter[ArrayT, DTypeLikeT, DTypeT, ...]): Adapter for specific array type.
+
+    Returns:
+        errs (ValidationErrorList[IncorrectDTypeError]):
+            list containing a single dtype error or an empty list.
+
+    (introduced ***v0.1***, last_modified ***v0.4***)
+    """
+    errs: ValidationErrorList[IncorrectDTypeError[DTypeLikeT, DTypeT]] = (
+        ValidationErrorList([])
+    )
+
+    if dtypelike == ...:
+        return errs
+
+    expected_dtype = ata.dtype_from_dtypelike(dtypelike)
+    if not ata.dtypes_equal(arr.dtype, expected_dtype):
+        errs.append(
+            ata.errors.incorrect_dtype(
+                actual_dtype=arr.dtype,
+                expected_dtype=expected_dtype,
+                expected_dtypelike=dtypelike,
+            )
+        )
+
+    return errs