valarray 0.4__tar.gz → 0.4.1__tar.gz

{valarray-0.4 → valarray-0.4.1}/.gitignore

@@ -3,6 +3,7 @@
 .coverage
 *egg-info
 dist*
+tach*
 
 ut_*
 temp*

{valarray-0.4 → valarray-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: valarray
-Version: 0.4
+Version: 0.4.1
 Summary: Library for validating numpy arrays.
 Project-URL: Homepage, https://codeberg.org/jfranek/valarray
 Author-email: "J. Franek" <franek.j27@email.cz>
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 
 In short, library for validating numpy arrays that also helps with static analysis and documentation. In long, see [Library rationale](#library-rationale).
 
-Currently intended primarily as a personal/hobby project (see [Caveats](#caveats))
+Currently intended primarily as a personal/hobby project (see [Caveats](#caveats)). Also not considered stable (see [Breaking changes](#breaking-changes)). 
 
 I have gotten away with using it in a professional setting, but YMMV. 
 
@@ -83,7 +83,12 @@ except ValidationException as v_exc:
 - [Catching exceptions](#catching-exceptions)
   - [Special exceptions and errors](#special-exceptions-and-errors)
   - [Generic Errors](#generic-errors)
+- [Settings](#settings)
 - [Caveats](#caveats)
+- [Changelog](#changelog)
+  - [0.4.1](#041)
+  - [0.4](#04)
+- [Breaking changes](#breaking-changes)
 
 # Library rationale
 This library aims to help with 3 issues encountered when working with numpy arrays:
@@ -691,8 +696,35 @@ These error types have subclasses ensuring proper type hints:
 - `InvalidArrayValuesError` -> `NumpyInvalidArrayValuesError`
 - `InvalidFieldValuesError` -> `NumpyInvalidFieldValuesError`
 
+# Settings
+Global settings for the library are defined in `valarray.settings` and can be modified using environment variables.
+| ***variable name*** | ***environment variable***   | default value | description                                         |
+|---------------------|------------------------------|---------------|-----------------------------------------------------|
+| function_cache_size | VALARRAY_FUNCTION_CACHE_SIZE | 512           | cache size for (internal) frequently used functions |
+
+
 
 # Caveats
 - I cannot guarantee that the test suite is foolproof ATM as I'm currently the only one testing this library.
 - Library has so far only been tested with `python==3.12` and `numpy==2.4.0`
-- Library isn't tested for performance, use in production only if the primary bottleneck is brain and not hardware.
+- Library isn't tested for performance, use in production only if the primary bottleneck is brain and not hardware.
+
+# Changelog
+## 0.4.1
+- added cache for often used functions
+- added __str__ and __len__ methods
+
+## 0.4
+- first version with all basic features: creating a validated array, validating dtype, shape, array and field values
+
+
+# Breaking changes
+- **0.4** -> **0.4.1**
+  - changed __str__ method for `Validator` to `.error_string` property (to allow different string representation for error messages and general printing)
+  - changed imports due to refactoring to simplify dependencies:
+    - `GenericErrors`
+      - from `valarray.core.errors_exceptions` -> from `valarray.core`
+    - `NumpyErrors`
+      - from `valarray.numpy.errors_exceptions` -> from `valarray.numpy`
+    - `AxisNameAndIdx`, `FieldNameAndIdx`
+      - from `valarray.core.axes_and_fields` -> from `valarray.core.data_structures`

{valarray-0.4 → valarray-0.4.1}/README.md

@@ -2,7 +2,7 @@
 
 In short, library for validating numpy arrays that also helps with static analysis and documentation. In long, see [Library rationale](#library-rationale).
 
-Currently intended primarily as a personal/hobby project (see [Caveats](#caveats))
+Currently intended primarily as a personal/hobby project (see [Caveats](#caveats)). Also not considered stable (see [Breaking changes](#breaking-changes)). 
 
 I have gotten away with using it in a professional setting, but YMMV. 
 
@@ -67,7 +67,12 @@ except ValidationException as v_exc:
 - [Catching exceptions](#catching-exceptions)
   - [Special exceptions and errors](#special-exceptions-and-errors)
   - [Generic Errors](#generic-errors)
+- [Settings](#settings)
 - [Caveats](#caveats)
+- [Changelog](#changelog)
+  - [0.4.1](#041)
+  - [0.4](#04)
+- [Breaking changes](#breaking-changes)
 
 # Library rationale
 This library aims to help with 3 issues encountered when working with numpy arrays:
@@ -675,8 +680,35 @@ These error types have subclasses ensuring proper type hints:
 - `InvalidArrayValuesError` -> `NumpyInvalidArrayValuesError`
 - `InvalidFieldValuesError` -> `NumpyInvalidFieldValuesError`
 
+# Settings
+Global settings for the library are defined in `valarray.settings` and can be modified using environment variables.
+| ***variable name*** | ***environment variable***   | default value | description                                         |
+|---------------------|------------------------------|---------------|-----------------------------------------------------|
+| function_cache_size | VALARRAY_FUNCTION_CACHE_SIZE | 512           | cache size for (internal) frequently used functions |
+
+
 
 # Caveats
 - I cannot guarantee that the test suite is foolproof ATM as I'm currently the only one testing this library.
 - Library has so far only been tested with `python==3.12` and `numpy==2.4.0`
-- Library isn't tested for performance, use in production only if the primary bottleneck is brain and not hardware.
+- Library isn't tested for performance, use in production only if the primary bottleneck is brain and not hardware.
+
+# Changelog
+## 0.4.1
+- added cache for often used functions
+- added __str__ and __len__ methods
+
+## 0.4
+- first version with all basic features: creating a validated array, validating dtype, shape, array and field values
+
+
+# Breaking changes
+- **0.4** -> **0.4.1**
+  - changed __str__ method for `Validator` to `.error_string` property (to allow different string representation for error messages and general printing)
+  - changed imports due to refactoring to simplify dependencies:
+    - `GenericErrors`
+      - from `valarray.core.errors_exceptions` -> from `valarray.core`
+    - `NumpyErrors`
+      - from `valarray.numpy.errors_exceptions` -> from `valarray.numpy`
+    - `AxisNameAndIdx`, `FieldNameAndIdx`
+      - from `valarray.core.axes_and_fields` -> from `valarray.core.data_structures`

valarray-0.4.1/docs/dependency_graphs/core.mmd

@@ -0,0 +1,30 @@
+graph TD
+    valarray.core.validators --> valarray.core.types
+    valarray.core.validators --> valarray.core.array_type_adapter
+    valarray.core.axes_and_fields --> valarray.core.validators
+    valarray.core.axes_and_fields --> valarray.core.types
+    valarray.core.errors_exceptions --> valarray.core.validators
+    valarray.core.errors_exceptions --> valarray.core.types
+    valarray.core.errors_exceptions --> valarray.core.data_structures
+    valarray.core.utils --> valarray.core.validators
+    valarray.core.utils --> valarray.core.errors_exceptions
+    valarray.core.utils --> valarray.core.axes_and_fields
+    valarray.core.utils --> valarray.core.types
+    valarray.core.utils --> valarray.core.array_type_adapter
+    valarray.core.array --> valarray.core.errors_exceptions
+    valarray.core.array --> valarray.core.axes_and_fields
+    valarray.core.array --> valarray.core.utils
+    valarray.core.array --> valarray.core.validation_functions
+    valarray.core.array --> valarray.core.validators
+    valarray.core.array --> valarray.core.array_type_adapter
+    valarray.core.array --> valarray.core.types
+    valarray.core.array_type_adapter --> valarray.core.types
+    valarray.core.validation_functions --> valarray.core.axes_and_fields
+    valarray.core.validation_functions --> valarray.core.utils
+    valarray.core.validation_functions --> valarray.core.validators
+    valarray.core.validation_functions --> valarray.core.errors_exceptions
+    valarray.core.validation_functions --> valarray.core.data_structures
+    valarray.core.validation_functions --> valarray.core.types
+    valarray.core.validation_functions --> valarray.core.array_type_adapter
+    valarray.core.data_structures
+    valarray.core.types

valarray-0.4.1/docs/dependency_graphs/core_validation_errors.mmd

@@ -0,0 +1,13 @@
+graph TD
+    valarray.core.errors_exceptions.validation_errors.values --> valarray.core.errors_exceptions.validation_errors.base
+    valarray.core.errors_exceptions.error_list --> valarray.core.errors_exceptions.validation_errors.base
+    valarray.core.errors_exceptions.error_list --> valarray.core.errors_exceptions.exceptions
+    valarray.core.errors_exceptions.validation_errors.array_creation --> valarray.core.errors_exceptions.validation_errors.base
+    valarray.core.errors_exceptions.validation_errors.dtype --> valarray.core.errors_exceptions.validation_errors.base
+    valarray.core.errors_exceptions.validation_errors.axes --> valarray.core.errors_exceptions.validation_errors.base
+    valarray.core.errors_exceptions.exceptions --> valarray.core.errors_exceptions.validation_errors.dtype
+    valarray.core.errors_exceptions.exceptions --> valarray.core.errors_exceptions.validation_errors.array_creation
+    valarray.core.errors_exceptions.exceptions --> valarray.core.errors_exceptions.validation_errors.base
+    valarray.core.errors_exceptions.exceptions --> valarray.core.errors_exceptions.error_list
+    valarray.core.errors_exceptions.validation_errors.base
+    valarray.core.errors_exceptions.validation_errors

valarray-0.4.1/docs/dependency_graphs/core_validation_functions.mmd

@@ -0,0 +1,15 @@
+graph TD
+    valarray.core.validation_functions.array_values --> valarray.core.validation_functions.utils
+    valarray.core.validation_functions.field_values.utils --> valarray.core.validation_functions.field_values.types_and_data_structures
+    valarray.core.validation_functions.field_values.utils --> valarray.core.validation_functions.utils
+    valarray.core.validation_functions.field_values.core --> valarray.core.validation_functions.field_values.utils
+    valarray.core.validation_functions.field_values.core --> valarray.core.validation_functions.field_values.types_and_data_structures
+    valarray.core.validation_functions.field_values.core --> valarray.core.validation_functions.shape
+    valarray.core.validation_functions.array --> valarray.core.validation_functions.shape
+    valarray.core.validation_functions.array --> valarray.core.validation_functions.dtype
+    valarray.core.validation_functions.array --> valarray.core.validation_functions.field_values.core
+    valarray.core.validation_functions.array --> valarray.core.validation_functions.array_values
+    valarray.core.validation_functions.field_values.types_and_data_structures
+    valarray.core.validation_functions.utils
+    valarray.core.validation_functions.shape
+    valarray.core.validation_functions.dtype

valarray-0.4.1/docs/dependency_graphs/numpy.mmd

@@ -0,0 +1,25 @@
+graph TD
+    valarray.numpy.array_type_adapter --> valarray.numpy.array_type_adapter.errors
+    valarray.numpy.array_type_adapter --> valarray.numpy.array_type_adapter.comparisons
+    valarray.numpy.array_type_adapter --> valarray.numpy.array_type_adapter.adapter
+    valarray.numpy.array_type_adapter.adapter --> valarray.numpy.types
+    valarray.numpy.array_type_adapter.adapter --> valarray.numpy.array_type_adapter.comparisons
+    valarray.numpy.array_type_adapter.adapter --> valarray.numpy.array_type_adapter.errors
+    valarray.numpy.validators --> valarray.numpy.types
+    valarray.numpy.array_type_adapter.errors --> valarray.numpy.types
+    valarray.numpy.array_type_adapter.errors --> valarray.numpy.errors_exceptions
+    valarray.numpy.array --> valarray.numpy.array_type_adapter
+    valarray.numpy.array --> valarray.numpy.types
+    valarray.numpy.array --> valarray.numpy.axes_and_fields
+    valarray.numpy.errors_exceptions --> valarray.numpy.types
+    valarray.numpy --> valarray.numpy.array_type_adapter
+    valarray.numpy --> valarray.numpy.axes_and_fields
+    valarray.numpy --> valarray.numpy.array
+    valarray.numpy --> valarray.numpy.validators
+    valarray.numpy.validation_functions --> valarray.numpy.array_type_adapter
+    valarray.numpy.validation_functions --> valarray.numpy.types
+    valarray.numpy.validation_functions --> valarray.numpy.validators
+    valarray.numpy.validation_functions --> valarray.numpy.axes_and_fields
+    valarray.numpy.axes_and_fields --> valarray.numpy.types
+    valarray.numpy.array_type_adapter.comparisons --> valarray.numpy.types
+    valarray.numpy.types

{valarray-0.4 → valarray-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "valarray"
-version = "0.4"
+version = "0.4.1"
 authors = [
   { name="J. Franek", email="franek.j27@email.cz" },
 ]

{valarray-0.4 → valarray-0.4.1}/requirements_dev.txt

@@ -2,4 +2,5 @@ setuptools
 pytest
 pytest-cov
 build
-twine
+twine
+dotenv

valarray-0.4.1/requirements_dev_optional.txt

@@ -0,0 +1 @@
+tach #creating dependency graphs

valarray-0.4.1/test_data/core/string_utils.py

@@ -0,0 +1,54 @@
+from valarray.core import Field
+from valarray.core.data_structures import HeadingAndLines
+
+CONSTRAINTS_STR_LT1 = "Constraints: < 1"
+CONSTRAINTS_STR_LT1_GE_NEG_5 = "Constraints: < 1, >= -5"
+
+VALIDATOR_HAL_DUMMY = HeadingAndLines("Validators:", ("Dummy: description",))
+
+FIELD_HAL_NO_IDX_NO_NAME = HeadingAndLines("Field < ? >", tuple())
+FIELD_HAL_NO_IDX_NAME = HeadingAndLines("Field < ? > : 'name'", tuple())
+FIELD_HAL_IDX_NO_NAME = HeadingAndLines("Field < 0 >", tuple())
+FIELD_HAL_IDX_NAME = HeadingAndLines("Field < 0 > : 'name'", tuple())
+
+FIELD_HAL_IDX_NAME_CONSTRAINTS_VALIDATORS = HeadingAndLines(
+    "Field < 0 > : 'name'",
+    (
+        "Constraints: < 1",
+        VALIDATOR_HAL_DUMMY,
+    ),
+)
+
+FIELD_STR = "Field < 0 > : 'first_field'"
+FIELD_HAL = HeadingAndLines("Field < 1 > : 'second_field'", ("Constraints: >= 0",))
+
+
+SCHEMA = (
+    12,
+    "second_axis",
+    (
+        "first_field",
+        Field("second_field", ge=0),
+    ),
+)
+SCHEMA_HAL = HeadingAndLines(
+    "schema:",
+    (
+        "Axis < 0 >",
+        "Axis < 1 > : 'second_axis'",
+        HeadingAndLines(
+            "Axis < 2 >",
+            (
+                FIELD_STR,
+                FIELD_HAL,
+            ),
+        ),
+    ),
+)
+
+ARRAY_NAME_AND_TYPE_STR = "TestValidatedArray (type: 'test')"
+DTYPE_STR = "data type: 'one' (DType1)"
+
+
+ARRAY = [1, 2, 3, 4]
+ARRAY_HAL = HeadingAndLines("values:", ("[1, 2, 3, 4]",))

{valarray-0.4 → valarray-0.4.1}/tests/core/classes_for_testing/array_and_dtype.py

@@ -39,5 +39,11 @@ class TestArray:
 
         return self
 
+    def __len__(self) -> int:
+        return len(self.val)
+
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}()"
+
+    def __str__(self) -> str:
+        return str(self.val)

{valarray-0.4 → valarray-0.4.1}/tests/core/classes_for_testing/array_type_adapter.py

@@ -1,6 +1,6 @@
 from types import EllipsisType
 
-from valarray.core import ArrayTypeAdapter
+from valarray.core.array_type_adapter import ArrayTypeAdapter
 from valarray.core.types import AxSizes
 
 from .array_and_dtype import TestArray, TestDtype, TestDtypeLike
@@ -11,6 +11,10 @@ from .errors_exceptions import TestErrors
 class TestArrayTypeAdapter(
     ArrayTypeAdapter[TestArray, TestDtypeLike, TestDtype, list[int], int]
 ):
+    @property
+    def type_name(self):
+        return "test"
+
     @property
     def errors(self):
         return TestErrors()
@@ -32,7 +36,7 @@ class TestArrayTypeAdapter(
     def create_empty_array(
         self, ax_sizes: AxSizes, dtypelike: TestDtypeLike | EllipsisType
     ) -> TestArray:
-        return TestArray(is_empty=True)
+        return TestArray(is_empty=True, shap=(0,))
 
     def is_array_empty(self, arr: TestArray) -> bool:
         return arr.is_empty

{valarray-0.4 → valarray-0.4.1}/tests/core/classes_for_testing/comparisons.py

@@ -1,5 +1,5 @@
 from tests.core.classes_for_testing.array_and_dtype import TestArray
-from valarray.core import Comparisons
+from valarray.core.array_type_adapter import Comparisons
 
 
 class TestComparisons(Comparisons[TestArray, list[int], int]):

{valarray-0.4 → valarray-0.4.1}/tests/core/classes_for_testing/errors_exceptions.py

@@ -1,8 +1,8 @@
 from dataclasses import dataclass
 
+from valarray.core.array_type_adapter import GenericErrors
 from valarray.core.errors_exceptions import (
     CannotCoerceDTypeError,
-    GenericErrors,
     IncorrectDTypeError,
     InvalidArrayValuesError,
     InvalidFieldValuesError,

{valarray-0.4 → valarray-0.4.1}/tests/core/classes_for_testing/validators.py

@@ -45,3 +45,21 @@ class TestValueErrorValidator(TestValidator):
     def validate(self, arr):
         if arr.val[0] < self.val:
             raise ValueError("value_error")
+
+
+@dataclass
+class TestWithDescriptionDummyValidator(TestValidator):
+    def validate(self, arr):
+        return True
+
+    @property
+    def description(self) -> str:
+        return "Dummy: description"
+
+
+class TestWitoutDescriptionAndReprDummyValidator(TestValidator):
+    def __init__(self, valid: bool = True):
+        self.valid = valid
+
+    def validate(self, arr):
+        return self.valid

{valarray-0.4 → valarray-0.4.1}/tests/core/errors_exceptions/test_values_errors.py

@@ -1,7 +1,7 @@
 import pytest
 
 from tests.core.classes_for_testing import TestComparisons, TestDummyValidator
-from valarray.core.axes_and_fields import AxisNameAndIdx, FieldNameAndIdx
+from valarray.core.data_structures import AxisNameAndIdx, FieldNameAndIdx
 from valarray.core.errors_exceptions import (
     InvalidArrayValuesError,
     InvalidFieldValuesError,

{valarray-0.4 → valarray-0.4.1}/tests/core/test_array.py

@@ -2,8 +2,9 @@ from contextlib import nullcontext as does_not_raise
 from typing import Any
 
 import pytest
-from classes_for_testing import TestArray, TestValidatedArray
+from classes_for_testing import TestArray, TestDtype, TestValidatedArray
 
+from tests.core.test_validators import TestWithDescriptionDummyValidator
 from valarray.core.errors_exceptions import ValidationException
 
 
@@ -63,3 +64,52 @@ def test_repr():
     arr = TestValidatedArray(TestArray(is_empty=True))
 
     assert repr(arr) == "TestValidatedArray.empty()"
+
+
+class TestTestValidatedArray(TestValidatedArray):
+    schema = ("n",)
+
+
+@pytest.mark.parametrize(
+    "v_arr, expected_length",
+    [
+        (TestTestValidatedArray.empty(), 0),
+        (TestTestValidatedArray(TestArray(val=[1, 2, 3], shap=(3,))), 3),
+    ],
+)
+def test_len(v_arr: TestValidatedArray, expected_length: int):
+    length = len(v_arr)
+
+    assert (
+        length == expected_length
+    ), "actual/expected values for 'length' are not equal"
+
+
+class ExampleTestArray(TestValidatedArray):
+    dtype = "one"
+    schema = (4,)
+    validators = (TestWithDescriptionDummyValidator(),)
+    lt = 5
+    ge = 0
+
+
+STR = """ExampleTestArray (type: 'test')
+  data type: 'one' (DType1)
+  schema:
+    Axis < 0 >
+  Constraints: < 5, >= 0
+  Validators:
+    Dummy: description
+  values:
+    [1, 2, 3, 4]"""
+
+
+def test_array_string():
+    expected_string = STR
+    string = str(
+        ExampleTestArray(TestArray(dtyp=TestDtype(1), shap=(4,), val=[1, 2, 3, 4]))
+    )
+
+    assert (
+        string == expected_string
+    ), "actual/expected values for 'string' are not equal"

valarray-0.4.1/tests/core/test_axes_and_fields.py

@@ -0,0 +1,22 @@
+from tests.core.test_validators import TestWithDescriptionDummyValidator
+from valarray.core.axes_and_fields import Field
+
+
+def test_field_string():
+    fld = Field(
+        name="example_field",
+        ge=-5,
+        lt=1,
+        validators=(TestWithDescriptionDummyValidator(),),
+    )
+
+    expected_string = """Field < ? > : 'example_field'
+  Constraints: < 1, >= -5
+  Validators:
+    Dummy: description"""
+
+    string = str(fld)
+
+    assert (
+        string == expected_string
+    ), "actual/expected values for 'string' are not equal"

valarray-0.4/tests/core/test_axes_and_fields.py → valarray-0.4.1/tests/core/test_data_structures.py

@@ -1,6 +1,6 @@
 import pytest
 
-from valarray.core.axes_and_fields import AxisNameAndIdx, FieldNameAndIdx
+from valarray.core.data_structures import AxisNameAndIdx, FieldNameAndIdx
 
 
 @pytest.mark.parametrize(

{valarray-0.4 → valarray-0.4.1}/tests/core/test_misc.py

@@ -4,7 +4,7 @@ from typing import Any
 import pytest
 
 from tests.core.classes_for_testing import TestComparisons
-from valarray.core import Comparisons
+from valarray.core.array_type_adapter import Comparisons
 
 
 class TestDifferentComparisons(Comparisons[Any, list[int], int]):