valarray 0.4__py3-none-any.whl

valarray/__init__.py

@@ -0,0 +1,6 @@
+"""
+`.core` ***module*** - Core classes, functions
+    on which concrete implemetations for specific array types are based upon.
+
+`.numpy` ***module*** - Validating numpy arrays.
+"""

valarray/core/__init__.py

@@ -0,0 +1,27 @@
+"""
+*import* `ValidatedArray` **ABC**
+
+*import* `ArrayTypeAdapter` **ABC**
+
+*import* `Comparisons` **ABC**
+
+*import* `Field` **dataclass**
+
+`.validation_functions` ***module***
+
+`.validators` ***module***
+
+`.errors_exceptions` ***module***
+
+`.types` ***module***
+
+`.axes_and_fields` ***module***
+
+`.utils` ***module***
+"""
+
+# pyright: reportUnusedImport=false
+from .array import ValidatedArray
+from .array_type_adapter import ArrayTypeAdapter
+from .axes_and_fields import Field
+from .comparisons import Comparisons

valarray/core/array.py

@@ -0,0 +1,121 @@
+from abc import ABC, abstractmethod
+from types import EllipsisType
+from typing import Any, Final, Generic, Optional, Self
+
+from valarray.core.axes_and_fields import AxesTuple
+
+from .array_type_adapter import ArrayTypeAdapter
+from .axes_and_fields import AxesTuple
+from .errors_exceptions import ValidationException
+from .types import ArrayIndicesT, ArrayT, ComparableValueT, DTypeLikeT, DTypeT
+from .utils import constraints_to_validators, setup_array
+from .validation_functions import validate_array
+from .validators.base import Validator
+
+
+class ValidatedArray(
+    ABC, Generic[ArrayT, DTypeLikeT, DTypeT, ArrayIndicesT, ComparableValueT]
+):
+    """Abstract base class for Validated Array implementations.
+    Subclasses need to implement:
+
+    **abstract property**
+    - `ata` -> returns a subclass of `ArrayTypeAdapter`
+
+    You should also specify generic type variables:
+    - `ArrayT` - type of array object
+    - `DTypeLikeT` - data type specification
+    - `DTypeT` - data type object
+    - `ArrayIndexT` - object(s) that can select values from array using `__getitem__` method.
+    - `ComparableValueT` - type of object an array can be compared with.
+
+    (introduced ***v0.1***, last_modified ***v0.3***)
+    """
+
+    dtype: DTypeLikeT | EllipsisType = ...
+    schema: AxesTuple[ArrayT, ArrayIndicesT, ComparableValueT] | EllipsisType = ...
+    validators: tuple[Validator[ArrayT, ArrayIndicesT], ...] = ()
+
+    lt: Optional[ComparableValueT] = None
+    le: Optional[ComparableValueT] = None
+    ge: Optional[ComparableValueT] = None
+    gt: Optional[ComparableValueT] = None
+    eq: Optional[ComparableValueT] = None
+
+    @property
+    @abstractmethod
+    def ata(
+        self,
+    ) -> ArrayTypeAdapter[ArrayT, DTypeLikeT, DTypeT, ArrayIndicesT, ComparableValueT]:
+        """Interface for operations that have different implementations for each array type."""
+
+    def __init__(self, obj: Any, validate=True, coerce_dtype=False) -> None:
+        self.is_validated = False
+
+        self._array: Final[ArrayT] = setup_array(
+            obj,
+            self.dtype,
+            coerce_dtype,
+            self.schema,
+            self.ata,
+            self.__class__.__name__,
+        )  # [!] CreateArrayException, CoerceDTypeException
+
+        if validate:
+            self.validate_array()
+
+    @classmethod
+    def wrap(cls, array: ArrayT) -> Self:
+        """Creates `ValidatedArray` without validation.
+
+        (introduced ***v0.1***, last_modified ***v0.1.1***)
+        """
+        return cls(array, validate=False)
+
+    @classmethod
+    def validate(cls, array: ArrayT) -> Self:
+        """Creates `ValidatedArray` by validating an existing array.
+
+        (introduced ***v0.1***, last_modified ***v0.1.1***)
+        """
+        return cls(array, validate=True)
+
+    @classmethod
+    def empty(cls) -> Self:
+        """Creates empty `ValidatedArray` by validating an existing array.
+
+        (introduced ***v0.1.1***)
+        """
+        return cls(None)
+
+    def validate_array(self):
+        """Validate array if it isn't already validated.
+
+        (introduced ***v0.1***, last_modified ***v.0.4***)"""
+        if self.is_validated:
+            return
+
+        # TODO: do not validate dtype if not necessary
+
+        validators = constraints_to_validators(
+            self.lt, self.le, self.ge, self.gt, self.eq, self.ata.comparisons
+        ) + list(self.validators)
+
+        errs = validate_array(
+            self._array, self.dtype, self.schema, validators, self.ata
+        )
+
+        if errs:
+            raise ValidationException(self.__class__.__name__, errs)
+
+        self.is_validated = True
+
+    def __repr__(self) -> str:
+        """(introduced ***v0.1***, last_modified ***v0.2.2***)"""
+        cls_name = self.__class__.__name__
+
+        if self.ata.is_array_empty((self._array)):
+            rep = f"{cls_name}.empty()"
+        else:
+            rep = f"{cls_name}({repr(self._array)})"
+        return rep

valarray/core/array_type_adapter.py

@@ -0,0 +1,109 @@
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from types import EllipsisType
+from typing import Any, Generic, Optional
+
+from .axes_and_fields import AxisNameAndIdx, FieldNameAndIdx
+from .comparisons import Comparisons
+from .errors_exceptions import GenericErrors
+from .types import ArrayT, AxSizes, ComparableValueT, DTypeLikeT, DTypeT
+from .types.generics import ArrayIndicesT
+
+
+class ArrayTypeAdapter(
+    ABC, Generic[ArrayT, DTypeLikeT, DTypeT, ArrayIndicesT, ComparableValueT]
+):
+    """Generic base array type adapter.
+
+    Type variables:
+        - `ArrayT` - type of array object
+        - `DTypeLikeT` - data type specification
+        - `DTypeT` - data type object
+        - `ArrayIndexT` - object(s) that can select values from array using `__getitem__` method.
+        - `ComparableValueT` - value array can be compared with
+        using `<`, `<=`, `==`, `=>`, `>` operators
+
+    Subclasses need to implement:
+        **abstract property**
+        - `errors` -
+            Subtypes of generic `ValidationError` classes.
+        - `array_type` -
+            Array type (to be used in `isinstance(obj, adapter.array_type)` check)
+        - `comparisons` -
+            Subtype of generic `Comparisons` class.
+
+        **abstract method**
+        - `create_array` -
+            Create an array object from data with specified dtype(like).
+        - `create_empty_array` -
+            Create an empty array object with specified dtype(like).
+        - `is_array_empty` -
+            Check if array is empty.
+        - `change_dtype` -
+            Change array data type.
+        - `dtype_from_dtypelike` -
+            Create dtype object from dtypelike.
+        - `dtypes_equal` -
+            Check if dtypes are equal
+        - `get_values` -
+            Get a list of values from array
+
+    (`dtypes_equal` and `get_values` are neccessary because `__eq__` and `__getitem__`
+    methods respectively can have different parameter names)
+
+    (introduced ***v0.1***, last_modified ***v0.4***)
+    """
+
+    @property
+    @abstractmethod
+    def errors(self) -> GenericErrors[ArrayT, DTypeLikeT, DTypeT, ArrayIndicesT]: ...
+
+    @property
+    @abstractmethod
+    def array_type(self) -> type[ArrayT]: ...
+
+    @property
+    @abstractmethod
+    def comparisons(self) -> Comparisons[ArrayT, ArrayIndicesT, ComparableValueT]:
+        """Methods used by `ComparisonValidator`"""
+
+    @abstractmethod
+    def change_dtype(self, arr: ArrayT, dtypelike: DTypeLikeT) -> ArrayT: ...
+
+    @abstractmethod
+    def create_array(
+        self, obj: Any, dtypelike: DTypeLikeT | EllipsisType
+    ) -> ArrayT: ...
+
+    @abstractmethod
+    def is_array_empty(self, arr: ArrayT) -> bool: ...
+
+    @abstractmethod
+    def create_empty_array(
+        self, ax_sizes: AxSizes, dtypelike: DTypeLikeT | EllipsisType
+    ) -> ArrayT: ...
+
+    @abstractmethod
+    def dtype_from_dtypelike(self, dtypelike: DTypeLikeT) -> DTypeT: ...
+
+    @abstractmethod
+    def dtypes_equal(self, actual_dtype: DTypeT, expected_dtype: DTypeT) -> bool: ...
+
+    @abstractmethod
+    def get_values(
+        self, arr: ArrayT, indices: Optional[ArrayIndicesT]
+    ) -> Optional[list[Any]]: ...
+
+    @abstractmethod
+    def select_subset(
+        self, arr: ArrayT, ax: AxisNameAndIdx, fields: Sequence[FieldNameAndIdx]
+    ) -> ArrayT: ...
+
+    @abstractmethod
+    def get_values_from_subset(
+        self,
+        arr: ArrayT,
+        indices: Optional[ArrayIndicesT],
+        ax: AxisNameAndIdx,
+        fields: Sequence[FieldNameAndIdx],
+    ) -> Optional[dict[FieldNameAndIdx, Any]]: ...

valarray/core/axes_and_fields.py

@@ -0,0 +1,127 @@
+"""
+*import* `AxesTuple` **TypeAlias** - defines axes of schema
+
+*import* `FieldsTuple` **TypeAlias** - defines fields of schema axis
+
+*import* `Field` **dataclass** - defines constraints on field
+"""
+
+from dataclasses import dataclass
+from typing import ClassVar, Generic, Optional, TypeAlias
+
+from valarray.core.validators import Validator
+
+from .types.generics import ArrayIndicesT, ArrayT, ComparableValueT
+
+
+@dataclass
+class Field(Generic[ArrayT, ArrayIndicesT, ComparableValueT]):
+    """Field of an array axis.
+
+    Arguments:
+        name (Optional[str]): Optional descriptive name of field. Defaults to `None`.
+        validators (tuple[Validator[ArrayT, ArrayIndicesT], ...]):
+            optional list of validators applied to field values
+        lt (Optional[ComparableValueT]):
+            Optional constraint -> field values less than. Defaults to None.
+        le (Optional[ComparableValueT]):
+            Optional constraint -> field values less or equal than. Defaults to None.
+        ge (Optional[ComparableValueT]):
+            Optional constraint -> field values greater than. Defaults to None.
+        gt (Optional[ComparableValueT]):
+            Optional constraint -> field values greater or equal than. Defaults to None.
+        eq (Optional[ComparableValueT]):
+            Optional constraint -> field values equal to. Defaults to None.
+
+    (introduced ***v0.4***)
+    """
+
+    name: Optional[str] = None
+    validators: tuple[Validator[ArrayT, ArrayIndicesT], ...] = ()
+
+    lt: Optional[ComparableValueT] = None
+    le: Optional[ComparableValueT] = None
+    ge: Optional[ComparableValueT] = None
+    gt: Optional[ComparableValueT] = None
+    eq: Optional[ComparableValueT] = None
+
+
+@dataclass(unsafe_hash=True)
+class _NameAndIdx:
+    _specifier: ClassVar[str] = "Field/Axis"
+    idx: int
+    name: Optional[str] = None
+
+    def __str__(self) -> str:
+        name_str = f": '{self.name}'" if self.name is not None else ""
+        return f"{self._specifier} < {self.idx} >{name_str}"
+
+
+@dataclass(unsafe_hash=True)
+class AxisNameAndIdx(_NameAndIdx):
+    """Name and index of axis.
+
+    Example:
+    ```
+    a_named = AxisNameAndIdx(name="example_axis", idx=3)
+    a = AxisNameAndIdx(idx=3)
+
+    print(a_named)
+    >>> Axis < 3 >: 'example_axis'
+
+    print(a)
+    >>> Axis < 3 >
+    ```
+
+    (introduced ***v0.4***)
+    """
+
+    _specifier: ClassVar[str] = "Axis"
+
+
+@dataclass(unsafe_hash=True)
+class FieldNameAndIdx(_NameAndIdx):
+    """Name and index of field.
+
+    Example:
+    ```
+    f_named = FieldNameAndIdx(name="example_field", idx=3)
+    f = FieldNameAndIdx(idx=3)
+
+    print(f_named)
+    >>> Field < 3 >: 'example_field'
+
+    print(f)
+    >>> Field < 3 >
+    ```
+
+    (introduced ***v0.4***)
+    """
+
+    _specifier: ClassVar[str] = "Field"
+
+
+FieldsTuple: TypeAlias = tuple[
+    str | Field[ArrayT, ArrayIndicesT, ComparableValueT], ...
+]
+"""Tuple of array fields.
+
+(introduced ***v0.1.1***, last_modified ***v0.4***)
+"""
+
+AxesTuple: TypeAlias = tuple[
+    str | int | FieldsTuple[ArrayT, ArrayIndicesT, ComparableValueT], ...
+]
+"""Tuple of array axes. Can be either name, size or a tuple of fields.
+```
+import valarray.core
+
+axes = (
+    16,
+    'items',
+    ('x','y', valarray.core.Field()),
+)
+```
+
+(introduced ***v0.1.1***, last_modified ***v0.4***)
+"""

valarray/core/comparisons.py

@@ -0,0 +1,71 @@
+from abc import ABC, abstractmethod
+from typing import Any, Generic
+
+from valarray.core.types import ArrayIndicesT, ArrayT, ComparableValueT
+
+
+class Comparisons(ABC, Generic[ArrayT, ArrayIndicesT, ComparableValueT]):
+    """Generic comparison functions.
+
+    Type variables:
+        - `ArrayT` - type of array object
+        - `ArrayIndexT` - object(s) that can select values from array using `__getitem__` method.
+        - `ComparableValueT` - value array can be compared with
+        using `<`, `<=`, `==`, `=>`, `>` operators
+
+    Subclasses need to implement:
+        **abstract method**
+        - `where_not_lt` -
+            Returns indices of values which are not less than value.
+        - `where_not_le` -
+            Returns indices of values which are not less than or equal value.
+        - `where_not_ge` -
+            Returns indices of values which are not greater than or equal value.
+        - `where_not_gt` -
+            Returns indices of values which are not greater than value.
+        - `where_not_eq` -
+            Returns indices of values which are not equal value.
+        - `n_indices` -
+            Returns number of indices.
+
+
+    (introduced ***v0.3***, last_modified ***v0.4***)
+    """
+
+    @abstractmethod
+    def where_not_lt(self, arr: ArrayT, value: ComparableValueT) -> ArrayIndicesT:
+        """(introduced ***v0.3***)"""
+
+    @abstractmethod
+    def where_not_le(self, arr: ArrayT, value: ComparableValueT) -> ArrayIndicesT:
+        """(introduced ***v0.3***)"""
+
+    @abstractmethod
+    def where_not_ge(self, arr: ArrayT, value: ComparableValueT) -> ArrayIndicesT:
+        """(introduced ***v0.3***)"""
+
+    @abstractmethod
+    def where_not_gt(self, arr: ArrayT, value: ComparableValueT) -> ArrayIndicesT:
+        """(introduced ***v0.3***)"""
+
+    @abstractmethod
+    def where_not_eq(self, arr: ArrayT, value: ComparableValueT) -> ArrayIndicesT:
+        """(introduced ***v0.3***)"""
+
+    @abstractmethod
+    def n_indices(self, indices: ArrayIndicesT) -> int:
+        """(introduced ***v0.3***)"""
+
+    def __hash__(self) -> int:
+        # HACK: For ComparisonValidator to be hashable, *Comparisons must be hashable.
+        # Because all instances of each type of *Comparisons class are the same
+        # I just convert class name into integer and use it as a hash
+        # using: https://stackoverflow.com/questions/61848516/convert-whole-ascii-string-into-a-int
+        cls_name = self.__class__.__name__
+        return int.from_bytes(cls_name.encode("utf-8"), byteorder="big", signed=False)
+
+    def __eq__(self, other: Any) -> bool:
+        try:
+            return hash(self) == hash(other)
+        except TypeError:
+            return False

valarray/core/errors_exceptions/__init__.py

@@ -0,0 +1,41 @@
+"""
+# Errors
+*import* `ValidationError` **ABC**
+
+*import* `CannotCreateArrayError` **ValidationError**
+
+*import* `IncorrectDTypeError` **ValidationError**
+
+*import* `CannotCoerceDTypeError` **ValidationError**
+
+*import* `IncorrectAxNumberError` **ValidationError**
+
+*import* `IncorrectAxSizesError` **ValidationError**
+
+*import* `InvalidArrayValuesError` **ValidationError**
+
+*import* `InvalidFieldValuesError` **ValidationError**
+
+
+# Exceptions
+*import* `ValidationException` **Exception**
+
+*import* `CreateArrayException` **Exception**
+
+*import* `CoerceDTypeException` **Exception**
+
+# Other
+*import* `ValidationErrorList` **UserList**
+
+*import* `GenericErrors` **dataclass**
+"""
+
+# pyright: reportUnusedImport=false
+from .error_list import ValidationErrorList
+from .exceptions import CoerceDTypeException, CreateArrayException, ValidationException
+from .generic import GenericErrors
+from .validation_errors.array_creation import CannotCreateArrayError
+from .validation_errors.axes import IncorrectAxNumberError, IncorrectAxSizesError
+from .validation_errors.base import ValidationError
+from .validation_errors.dtype import CannotCoerceDTypeError, IncorrectDTypeError
+from .validation_errors.values import InvalidArrayValuesError, InvalidFieldValuesError

valarray/core/errors_exceptions/error_list.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from collections import UserList
+from typing import Generic, Sequence, overload
+
+from .validation_errors.base import SelectedValidationErrorT, ValidationErrorT
+
+_ErrorTypes = (
+    type[SelectedValidationErrorT] | tuple[type[SelectedValidationErrorT], ...]
+)
+"""Error type or a tuple of error types. 
+For example `IncorrectAxSizesError` or `(IncorrectAxSizesError, IncorrectDTypeError)`"""
+
+
+class ValidationErrorList(UserList[ValidationErrorT], Generic[ValidationErrorT]):
+    """List of `ValidationError` objects.
+
+    Compared to built-in list, implements two methods:
+        - `raise_`/`raise_on_errors` - raises `ValidationException` if not empty.
+        - `__getitem__` - in addition to indexing by integer or slice can be filtered by type
+            or tuple of types of `ValidationError`
+
+            ### Examples:
+            ```
+            errs = ValidationErrorList(
+                [IncorrectAxSizesError(...), IncorrectDTypeError(...), InvalidFieldValuesError(...)]
+                )
+
+            err = errs[0]
+            >>> IncorrectAxSizesError(...)
+
+            sliced_errs = errs[:2]
+            >>> [IncorrectAxSizesError(...), IncorrectDTypeError(...)]
+
+            filtered_errs_type = errs[IncorrectAxSizesError]
+            >>> [IncorrectAxSizesError(...)]
+
+            filtered_errs_tuple = errs[(IncorrectAxSizesError, InvalidFieldValuesError)]
+            >>> [IncorrectAxSizesError(...), InvalidFieldValuesError(...)]
+            ```
+    """
+
+    def __init__(self, errs: Sequence[ValidationErrorT]):
+        super().__init__(errs)
+
+    def raise_(self):
+        """Raises `ValidationException` if there are errors."""
+        # NOTE: scoped import to prevent circular import
+        # ValidationException -> ValidationErrorList -> ValidationException
+        from .exceptions import ValidationException
+
+        if self.data:
+            raise ValidationException(None, ValidationErrorList(self.data))
+
+    raise_on_errors = raise_
+
+    @overload
+    def __getitem__(self, i: int) -> ValidationErrorT: ...
+
+    @overload
+    def __getitem__(self, i: slice) -> ValidationErrorList[ValidationErrorT]: ...
+
+    @overload
+    def __getitem__(
+        self,
+        i: _ErrorTypes[SelectedValidationErrorT],
+    ) -> ValidationErrorList[SelectedValidationErrorT]: ...
+
+    def __getitem__(
+        self,
+        i: int | slice | _ErrorTypes[SelectedValidationErrorT],
+    ) -> (
+        ValidationErrorList[SelectedValidationErrorT]
+        | ValidationErrorList[ValidationErrorT]
+        | ValidationErrorT
+    ):
+        if isinstance(i, (type, tuple)):
+            filtered_errs: list[SelectedValidationErrorT] = [
+                err for err in self.data if isinstance(err, i)
+            ]  # pyright: ignore[reportAssignmentType] | I don't know why pyright complains
+            items = ValidationErrorList(filtered_errs)
+        elif isinstance(i, slice):
+            items = type(self)(self.data[i])
+        else:
+            items = self.data[i]
+
+        return items

valarray/core/errors_exceptions/exceptions.py

@@ -0,0 +1,75 @@
+from typing import Generic, Optional
+
+from .error_list import ValidationErrorList
+from .validation_errors.array_creation import CannotCreateArrayError
+from .validation_errors.base import ValidationErrorT
+from .validation_errors.dtype import CannotCoerceDTypeError
+
+
+# TODO: ugh, typing issues, pls fix ->
+# except ValidationException as exc:
+#    exc.errs -> 'Unknown'
+class ValidationException(ValueError, Generic[ValidationErrorT]):
+    """Exception caused by failed array validation.
+
+    Attributes:
+        cls_name (Optional[str]):
+            Optional name of ValidatedArray subclass that caused this exception.
+        errs (ValidationErrorList[ValidationError):
+            List of validation errors responsible.
+
+    (introduced ***v0.1***, last_modified ***v0.4***)
+    """
+
+    def __init__(
+        self,
+        cls_name: Optional[str],
+        errs: ValidationErrorList[ValidationErrorT],
+        *args: object,
+    ) -> None:
+
+        super().__init__(*args)
+
+        self.cls_name = cls_name
+        self.errs = errs
+        """List of validation errors."""
+
+    def __str__(self) -> str:
+        prefix = f"'{self.cls_name}' " if self.cls_name is not None else ""
+        err_msgs = "\n".join([e.msg for e in self.errs])
+        return f"{prefix}validation failed:\n" + err_msgs
+
+
+class CreateArrayException(ValidationException):
+    """Special case of `ValidationException`
+    on failure to create a validated array from generic data.
+
+    Attributes:
+        cls_name (str):
+            Name of ValidatedArray subclass that caused this exception.
+        errs (ValidationErrorList[CannotCreateArrayError]): List containing error responsible.
+
+    (introduced ***v0.1***, last_modified ***v0.4***)
+    """
+
+    def __init__(self, cls_name: str) -> None:
+        super().__init__(
+            cls_name=cls_name, errs=ValidationErrorList([CannotCreateArrayError()])
+        )
+
+
+class CoerceDTypeException(ValidationException):
+    """Special case of `ValidationException`
+    on failure to coerce the data type of an existing array.
+
+    Attributes:
+        cls_name (str):
+            Name of ValidatedArray subclass that caused this exception.
+        errs (ValidationErrorList[CannotCoerceDTypeError]):
+            List containing error with actual and target data type information.
+
+    (introduced ***v0.1***, last_modified ***v0.4***)
+    """
+
+    def __init__(self, cls_name: str, err: CannotCoerceDTypeError) -> None:
+        super().__init__(cls_name=cls_name, errs=ValidationErrorList([err]))