valarray 0.4__py3-none-any.whl

valarray/numpy/array.py

@@ -0,0 +1,63 @@
+from types import EllipsisType
+from typing import Any, Generic
+
+import numpy as np
+import numpy.typing as npt
+
+from valarray.core import ValidatedArray
+from valarray.core.validators import Validator
+
+from .array_type_adapter import NumpyArrayTypeAdapter
+from .axes_and_fields import AxesTuple
+from .types import AdvancedIndex, NumpyDTypeT
+
+
+class ValidatedNumpyArray(
+    ValidatedArray[npt.NDArray[Any], npt.DTypeLike, np.dtype, AdvancedIndex, object],
+    Generic[NumpyDTypeT],
+):
+    """Base validated numpy array.
+
+    To implement a validated array, inherit from this class and set the following class variables:
+    - `dtype` - expected data type specification (such as `float`,`"float64"`, `np.float64`).
+        If not specified, do not validate data type.
+        For full list of accepted values, see:
+            https://numpy.org/doc/stable/reference/arrays.dtypes.html#specifying-and-constructing-data-types
+    - `schema` - expected shape specification (of type `valarray.numpy.axes_and_fields.AxesTuple`).
+        If not specified, do not validate shape.
+    - `lt`/`le`/`ge`/`gt`/`eq` - basic array value constraints -> less (or equal) than, greater (or equal) than, equal to
+    - `validators` - optional list of validators applied to the whole array.
+
+    You should also specify generic type variables:
+    - `NumpyDTypeT` - data type hint for array accessed through `array`/`a_` property.
+
+    ```
+    class ExampleArray(ValidatedNumpyArray):
+        dtype = np.float32
+
+    class ExampleArray2(ValidatedNumpyArray):
+        dtype = "float32"
+    ```
+
+    (introduced ***v0.1***, last_modified ***v0.3***)
+    """
+
+    schema: AxesTuple[NumpyDTypeT] | EllipsisType = ...
+    validators: tuple[
+        Validator[npt.NDArray[NumpyDTypeT], AdvancedIndex],
+        ...,
+    ] = ()
+
+    @property
+    def ata(self) -> NumpyArrayTypeAdapter:
+        return NumpyArrayTypeAdapter()
+
+    @property
+    def array(self) -> npt.NDArray[NumpyDTypeT]:
+        """Access underlying `np.array`
+
+        (introduced ***v0.1***)
+        """
+        return self._array
+
+    a_ = array

valarray/numpy/array_type_adapter.py

@@ -0,0 +1,133 @@
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from valarray.core import ArrayTypeAdapter
+from valarray.core.axes_and_fields import FieldNameAndIdx
+
+from .comparisons import NumpyComparisons
+from .errors_exceptions import NumpyErrors
+from .types import AdvancedIndex
+
+
+class NumpyArrayTypeAdapter(
+    ArrayTypeAdapter[
+        npt.NDArray[Any],
+        npt.DTypeLike,
+        np.dtype[Any],
+        AdvancedIndex,
+        Any,
+    ]
+):
+    """Adapter for numpy arrays.
+
+    (introduced ***v0.1***, last_modified ***v0.3***)
+    """
+
+    @property
+    def errors(self):
+        return NumpyErrors()
+
+    @property
+    def array_type(self):
+        """(introduced ***v0.1***)"""
+        return np.ndarray
+
+    @property
+    def comparisons(self) -> NumpyComparisons:
+        """(introduced ***v0.3***)"""
+        return NumpyComparisons()
+
+    def change_dtype(self, arr, dtypelike):
+        """(introduced ***v0.1***)"""
+        return arr.astype(dtypelike)
+
+    def create_array(self, obj, dtypelike):
+        """(introduced ***v0.1***)"""
+        if dtypelike == ...:
+            arr = np.asarray(obj, None)
+        else:
+            arr = np.array(obj, dtypelike)
+
+        return arr
+
+    def is_array_empty(self, arr) -> bool:
+        """(introduced ***v0.2.2***)"""
+        return arr.size < 1
+
+    def create_empty_array(self, ax_sizes, dtypelike):
+        """(introduced ***v0.1.1***)"""
+        dt = None if dtypelike == ... else dtypelike
+
+        # Replace first and all unknown sizes with 0
+        # (3,2, None, 1) => (0,2,0,1)
+        shape = [0 if s is None else s for s in ax_sizes]
+        if len(shape) > 0:
+            shape[0] = 0
+
+        return np.empty(shape, dt)
+
+    def dtype_from_dtypelike(self, dtypelike):
+        """(introduced ***v0.1***)"""
+        return np.dtype(dtypelike)
+
+    def dtypes_equal(self, actual_dtype, expected_dtype) -> bool:
+        """(introduced ***v0.1***)"""
+        return actual_dtype == expected_dtype
+
+    def get_values(self, arr, indices):
+        """Returns array values from indices defined by a boolean array
+        or a tuple of integer arrays.
+
+        (introduced ***v0.3***)"""
+        if indices is None:
+            return None
+
+        try:
+            vals = arr[indices].tolist()
+        except IndexError:
+            # TODO: add logger and warning
+            vals = None
+
+        return vals
+
+    def select_subset(self, arr, ax, fields):
+        selection = []
+        for ax_i in range(len(arr.shape)):
+            if ax_i == ax.idx:
+                s = tuple(f.idx for f in fields)
+            else:
+                s = slice(None, None)
+
+            selection.append(s)
+
+        return arr[*selection]
+
+    def get_values_from_subset(
+        self,
+        arr,
+        indices,
+        ax,
+        fields,
+    ):
+        if indices is None:
+            return None
+
+        dic: dict[FieldNameAndIdx, list[Any]] = {}
+
+        indices_tuple = indices if isinstance(indices, tuple) else np.where(indices)
+
+        val_arr = arr[indices_tuple]
+
+        field_idx_arr = indices_tuple[ax.idx]
+
+        for i, f in enumerate(fields):
+            vals = val_arr[field_idx_arr == i]
+
+            if len(vals) < 1:
+                continue
+
+            dic[f] = vals.tolist()
+
+        return dic

valarray/numpy/axes_and_fields.py

@@ -0,0 +1,83 @@
+"""
+*import* `AxesTuple` **TypeAlias** - defines axes of schema
+
+*import* `FieldsTuple` **TypeAlias** - defines fields of schema axis
+
+*import* `Field` **valarray.core.Field** - defines constraints on field
+"""
+
+from dataclasses import dataclass
+from typing import Generic, TypeAlias
+
+import numpy.typing as npt
+
+import valarray.core
+from valarray.numpy.types import AdvancedIndex, NumpyDTypeT
+
+# NOTE: Need to specialize Field, FieldsTuple and AxesTuple,
+# because Field with no set validators is not specialized with respect to array type (ArrayT).
+# (Essentially trying to assign:
+# Field[ArrayP, Any, Any] -> Field[npt.NDArray[Any], AdvancedIndex, object])
+
+
+@dataclass
+class Field(
+    valarray.core.Field[npt.NDArray[NumpyDTypeT], AdvancedIndex, object],
+    Generic[NumpyDTypeT],
+):
+    """Field of an array axis.
+
+    Arguments:
+        name (Optional[str]): Optional descriptive name of field. Defaults to `None`.
+        validators (tuple[Validator[npt.NDArray[NumpyDTypeT], AdvancedIndex], ...]):
+            optional list of validators applied to field values
+        lt (Optional[Any]):
+            Optional constraint -> field values less than. Defaults to None.
+        le (Optional[Any]):
+            Optional constraint -> field values less or equal than. Defaults to None.
+        ge (Optional[Any]):
+            Optional constraint -> field values greater than. Defaults to None.
+        gt (Optional[Any]):
+            Optional constraint -> field values greater or equal than. Defaults to None.
+        eq (Optional[Any]):
+            Optional constraint -> field values equal to. Defaults to None.
+
+    (introduced ***v0.4***)
+
+    Examples:
+    ```
+    from typing import Any
+
+    from valarray.numpy import Field, NumpyValidator
+
+    class ExampleNumpyValidator(NumpyValidator[Any]):
+        def validate(self, arr):
+            return True
+
+    f1 = Field("example_named_field", ge=0)
+    f2 = Field(gt=10, validators=(ExampleNumpyValidator(),))
+
+    ```
+    """
+
+
+FieldsTuple: TypeAlias = tuple[str | Field[NumpyDTypeT], ...]
+"""Tuple of numpy array fields.
+
+(introduced ***v0.4***)
+"""
+
+AxesTuple: TypeAlias = tuple[str | int | FieldsTuple[NumpyDTypeT], ...]
+"""Tuple of numpy array axes. Can be either name, size or a tuple of fields.
+```
+import valarray.numpy
+
+axes = (
+    16,
+    "items",
+    ("x", "y", "length", valarray.numpy.Field()),
+)
+```
+
+(introduced ***v0.4***)
+"""

valarray/numpy/comparisons.py

@@ -0,0 +1,135 @@
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from valarray.core import Comparisons
+from valarray.numpy.types import AdvancedIndex
+
+
+class NumpyComparisons(Comparisons[npt.NDArray, AdvancedIndex, Any]):
+    """(introduced ***v0.3***)"""
+
+    def where_not_lt(self, arr, value):
+        """Returns indices of values which are ***not* less than** value.
+
+        Indices are tuple of integer arrays of length equal to number of array axes
+
+        -> `(np.array([idx0_axis0, idx1_axis0, ...]), np.array([idx0_axis1, idx1_axis1, ...]), ...)`
+
+        ### Example:
+        ``` # *not* less than 0
+        arr = np.array(
+            [
+                [-1 ,0],
+                [0, 1],
+            ]
+        )
+        indices = (np.array([0, 1, 1]), np.array([1, 0, 1]))
+        ```
+
+        (introduced ***v0.3***)
+        """
+        return np.where(~(arr < value))
+
+    def where_not_le(self, arr, value):
+        """Returns indices of values which are ***not* less than or equal** value.
+
+        Indices are tuple of integer arrays of length equal to number of array axes
+
+        -> `(np.array([idx0_axis0, idx1_axis0, ...]), np.array([idx0_axis1, idx1_axis1, ...]), ...)`
+
+        ### Example:
+        ``` # *not*  less than or equal 0
+        arr = np.array(
+            [
+                [-1 ,0],
+                [0, 1],
+            ]
+        )
+        indices = (np.array([0, 1, 1]), np.array([1, 0, 1]))
+        ```
+
+        (introduced ***v0.3***)
+        """
+        return np.where(~(arr <= value))
+
+    def where_not_ge(self, arr, value):
+        """Returns indices of values which are ***not* greater than or equal** value.
+
+        Indices are tuple of integer arrays of length equal to number of array axes
+
+        -> `(np.array([idx0_axis0, idx1_axis0, ...]), np.array([idx0_axis1, idx1_axis1, ...]), ...)`
+
+        ### Example:
+        ``` # *not*  greater than or equal 0
+        arr = np.array(
+            [
+                [-1 ,0],
+                [0, 1],
+            ]
+        )
+        indices = (np.array([0, 1, 1]), np.array([1, 0, 1]))
+        ```
+
+        (introduced ***v0.3***)
+        """
+        return np.where(~(arr >= value))
+
+    def where_not_gt(self, arr, value):
+        """Returns indices of values which are ***not* greater than** value.
+
+        Indices are tuple of integer arrays of length equal to number of array axes
+
+        -> `(np.array([idx0_axis0, idx1_axis0, ...]), np.array([idx0_axis1, idx1_axis1, ...]), ...)`
+
+        ### Example:
+        ``` # *not*  greater than 0
+        arr = np.array(
+            [
+                [-1 ,0],
+                [0, 1],
+            ]
+        )
+        indices = (np.array([0, 1, 1]), np.array([1, 0, 1]))
+        ```
+
+        (introduced ***v0.3***)
+        """
+        return np.where(~(arr > value))
+
+    def where_not_eq(self, arr, value):
+        """Returns indices of values which are ***not* equal** value.
+
+        Indices are tuple of integer arrays of length equal to number of array axes
+
+        -> `(np.array([idx0_axis0, idx1_axis0, ...]), np.array([idx0_axis1, idx1_axis1, ...]), ...)`
+
+        ### Example:
+        ``` # *not*  equal 0
+        arr = np.array(
+            [
+                [-1 ,0],
+                [0, 1],
+            ]
+        )
+        indices = (np.array([0, 1, 1]), np.array([1, 0, 1]))
+        ```
+
+        (introduced ***v0.3***)
+        """
+        return np.where(~(arr == value))
+
+    def n_indices(self, indices):
+        """Counts the number of indices.
+
+        (introduced ***v0.3***)
+        """
+        if isinstance(indices, np.ndarray) and indices.dtype == np.bool_:
+            n = int(indices.sum())
+        elif len(indices) == 0:
+            n = 0
+        else:
+            n = len(indices[0])
+
+        return n

valarray/numpy/errors_exceptions.py

@@ -0,0 +1,172 @@
+"""
+*import* `NumpyIncorrectDTypeError` **ValidationError**
+
+*import* `NumpyCannotCoerceDTypeError` **ValidationError**
+
+*import* `NumpyInvalidArrayValuesError` **ValidationError**
+
+*import* `NumpyErrors` **dataclass**
+"""
+
+from dataclasses import dataclass
+from typing import Any, Self
+
+import numpy as np
+import numpy.typing as npt
+
+from valarray.core.errors_exceptions import (
+    CannotCoerceDTypeError,
+    GenericErrors,
+    IncorrectDTypeError,
+    InvalidArrayValuesError,
+    InvalidFieldValuesError,
+)
+
+from .types import AdvancedIndex
+
+
+class NumpyIncorrectDTypeError(IncorrectDTypeError[npt.DTypeLike, np.dtype]):
+    """***Validation error:*** Array has the wrong data type.
+
+    Attributes:
+        actual_dtype (np.dtype): Data type of the actual array.
+        expected_dtype (np.dtype): Expected data type.
+        expected_dtypelike (npt.DTypeLike):
+            Expected data type specification (`numpy.typing.DTypeLike`)
+            from `ValidatedArray.dtype`.
+
+    Examples:
+    ```
+    err = NumpyIncorrectDTypeError(
+        np.dtype(np.float32), np.dtype(np.float64), np.float64
+    )
+    print(err.msg)
+    >>> "Incorrect DType: 'float32', expected 'float64'."
+    ```
+
+    (introduced ***v0.2.4***)
+    """
+
+
+class NumpyCannotCoerceDTypeError(CannotCoerceDTypeError[npt.DTypeLike, np.dtype]):
+    """***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 (np.dtype): Data type of array passed to `ValidatedArray.__init__`.
+        target_dtype (np.dtype): Data type to convert to (as a data type object).
+        target_dtypelike (npt.DTypeLike):
+            Expected data type specification (`numpy.typing.DTypeLike`) from `ValidatedArray.dtype`.
+
+    Examples:
+    ```
+    err = NumpyCannotCoerceDTypeError(np.dtype("<U1"), np.dtype(int), int)
+    print(err.msg)
+    >>> "Cannot coerce data type from: '<U1' to 'int64'."
+    ```
+
+    (introduced ***v0.2.4***)
+    """
+
+
+class NumpyInvalidArrayValuesError(
+    InvalidArrayValuesError[npt.NDArray[Any], AdvancedIndex]
+):
+    """***ValidationError:*** Array has wrong values.
+
+    Attributes:
+        validator: (Validator[npt.NDArray[Any], AdvancedIndex]):
+            Validator applied to the whole array.
+        invalid_values (Optional[list[Any]]):
+            Values causing the validation to fail. Defaults to None.
+        invalid_indices (Optional[AdvancedIndex]): Indices of invalid values.
+        result_msg (Optional[str]): Optional message returned by validator.
+
+    Examples:
+    ```
+    err = NumpyInvalidArrayValuesError(
+        validator=ExampleValidator("bool"),
+        invalid_values=[1],
+        invalid_indices=np.array([[1, 1, 0], [1, 0, 1]], dtype=np.bool_),
+    )
+    print(err.msg)
+    >>> Invalid Array Values (ExampleValidator):
+        [1]
+
+    err = NumpyInvalidArrayValuesError(
+        validator=ExampleValidator("tuple"),
+        invalid_values=[1],
+        invalid_indices=(np.array([0, 1]), np.array([2, 1])),
+    )
+
+    print(err.msg)
+    >>> Invalid Array Values (ExampleValidator):
+        [1]
+    ```
+
+    (introduced ***v0.3***, last_modified ***v0.4***)"""
+
+    def __eq__(self, other: Self):
+        other_vars = vars(other)
+
+        for k, v in vars(self).items():
+            other_v = other_vars.get(k)
+
+            # NOTE: stack, because field can be a tuple of arrays.
+            # pyright complains, but numpy can actually stack `None's`
+            stacked_v = np.stack([v])
+            stacked_other_v = np.stack(
+                [other_v]  # pyright: ignore[reportArgumentType,reportCallIssue]]
+            )
+
+            if not np.all(stacked_v == stacked_other_v):
+                return False
+
+        return True
+
+
+class NumpyInvalidFieldValuesError(
+    InvalidFieldValuesError[npt.NDArray[Any], AdvancedIndex]
+):
+    """***ValidationError:*** Field or fields have wrong values.
+
+    Attributes:
+        validator: (Validator[npt.NDArray[Any], AdvancedIndex]):
+            Validator applied to array field(s).
+        invalid_values (Optional[InvalidFieldValues]):
+            Values causing the validation to fail, organized by axis and field. Defaults to None.
+
+    Examples:
+    ```
+    err = NumpyInvalidFieldValuesError(
+        validator=IsEvenValidator("bool"),
+        invalid_values={
+            AxisNameAndIdx(1, "example_axis"): {
+                FieldNameAndIdx(0, "example_field"): [1]
+            }
+        },
+    )
+    print(err.msg)
+    >>> Invalid Field Values (IsEvenValidator):
+        Axis < 1 >: 'example_axis'
+                Field < 0 >: 'example_field': [1]
+    ```
+
+    (introduced ***v0.4***)
+    """
+
+
+@dataclass
+class NumpyErrors(
+    GenericErrors[npt.NDArray[Any], npt.DTypeLike, np.dtype, AdvancedIndex]
+):
+    """(introduced ***v0.2.4***, last_modified ***v0.4***)"""
+
+    incorrect_dtype: type[NumpyIncorrectDTypeError] = NumpyIncorrectDTypeError
+    cannot_coerce_dtype: type[NumpyCannotCoerceDTypeError] = NumpyCannotCoerceDTypeError
+    invalid_array_values: type[NumpyInvalidArrayValuesError] = (
+        NumpyInvalidArrayValuesError
+    )
+    invalid_field_values: type[NumpyInvalidFieldValuesError] = (
+        NumpyInvalidFieldValuesError
+    )

valarray/numpy/types.py

@@ -0,0 +1,32 @@
+"""
+*import* `NumpyDTypeT` **TypeVar**
+
+*import* `AdvancedIndex` **type**
+"""
+
+from typing import TypeVar
+
+import numpy as np
+import numpy.typing as npt
+
+NumpyDTypeT = TypeVar("NumpyDTypeT", bound=np.generic)
+
+type AdvancedIndex = npt.NDArray[np.bool_] | tuple[npt.NDArray[np.integer], ...]
+"""Advanced numpy index using:
+- a boolean array 
+- tuple of integer arrays (length == nuber of array axes)
+
+### Examples:
+```
+indices = np.array(
+    [
+        [False, False, False],
+        [True, False, False],
+        [False, False, True],
+    ]
+)
+
+indices = (np.array([0, 1, 1]), np.array([1, 0, 1]))
+```
+(introduced ***v0.3***)
+"""