From 90bf105ad18d201ccabafc273da3585e3633ee12 Mon Sep 17 00:00:00 2001 From: Simeon Ehrig Date: Thu, 25 Jan 2024 13:13:17 +0100 Subject: [PATCH] implement Python types related to the naming conventions - Python 3.10+ is required because of the type alias - improve naming.md --- .github/workflows/testDeploy.yml | 2 +- bashi/types.py | 19 +++++++++++++++++++ bashi/utils.py | 7 ++++--- docs/naming.md | 18 ++++++++++-------- pyproject.toml | 2 +- tests/test_filter_adapter.py | 19 ++++++++++--------- 6 files changed, 45 insertions(+), 22 deletions(-) create mode 100644 bashi/types.py diff --git a/.github/workflows/testDeploy.yml b/.github/workflows/testDeploy.yml index caa762d..3988491 100644 --- a/.github/workflows/testDeploy.yml +++ b/.github/workflows/testDeploy.yml @@ -15,7 +15,7 @@ jobs: needs: formatter strategy: matrix: - python-version: ['3.9', '3.10', '3.11', '3.12'] + python-version: ['3.10', '3.11', '3.12'] name: Run unit tests with Python ${{ matrix.python-version }} steps: - uses: actions/checkout@v4 diff --git a/bashi/types.py b/bashi/types.py new file mode 100644 index 0000000..70f9839 --- /dev/null +++ b/bashi/types.py @@ -0,0 +1,19 @@ +"""bashi data types""" + +from typing import TypeAlias, Tuple, List, Callable +from collections import OrderedDict +from packaging.version import Version + +Parameter: TypeAlias = str +ValueName: TypeAlias = str +ValueVersion: TypeAlias = Version +ParameterValue: TypeAlias = Tuple[ValueName, ValueVersion] +ParameterValueList: TypeAlias = List[ParameterValue] +ParameterValueMatrix: TypeAlias = OrderedDict[Parameter, ParameterValueList] +ParameterValuePair: TypeAlias = OrderedDict[Parameter, ParameterValue] +ParameterValueTuple: TypeAlias = OrderedDict[Parameter, ParameterValue] +Combination: TypeAlias = OrderedDict[Parameter, ParameterValue] +CombinationList: TypeAlias = List[Combination] + +# function signature of a filter function +FilterFunction: TypeAlias = Callable[[OrderedDict[str, Tuple[str, Version]]], bool] diff --git a/bashi/utils.py b/bashi/utils.py index 611d855..9fd1ae6 100644 --- a/bashi/utils.py +++ b/bashi/utils.py @@ -1,9 +1,10 @@ """Different helper functions for bashi""" -from typing import Dict, Callable, Tuple, List +from typing import Dict, Tuple, List from collections import OrderedDict from packaging.version import Version from typeguard import typechecked +from bashi.types import FilterFunction, ParameterValueTuple class FilterAdapter: @@ -40,7 +41,7 @@ def filter_function(row: OrderedDict[str, Tuple[str, Version]]): def __init__( self, param_map: Dict[int, str], - filter_func: Callable[[OrderedDict[str, Tuple[str, Version]]], bool], + filter_func: FilterFunction, ): """Create a new FilterAdapter, see class doc string. @@ -67,7 +68,7 @@ def __call__(self, row: List[Tuple[str, Version]]) -> bool: Returns: bool: Returns True, if the parameter-value-tuple is valid """ - ordered_row: OrderedDict[str, Tuple[str, Version]] = OrderedDict() + ordered_row: ParameterValueTuple = OrderedDict() for index, param_name in enumerate(row): ordered_row[self.param_map[index]] = param_name return self.filter_func(ordered_row) diff --git a/docs/naming.md b/docs/naming.md index ef1b828..64f2ac4 100644 --- a/docs/naming.md +++ b/docs/naming.md @@ -1,17 +1,19 @@ # Naming -The [pair-wise testing](https://en.wikipedia.org/wiki/All-pairs_testing) takes amount of input values grouped by a specific meaning and creates many combinations of the values with specific rules. The following guide give the input and output values specific names, which will be used for documentation purpose and also naming variables and parameters in the source code. All names has the Python data type in brackets. +The [pair-wise testing](https://en.wikipedia.org/wiki/All-pairs_testing) takes amount of input values grouped by a specific meaning and creates many combinations of the values with specific rules. The following guide give the input and output values specific names, which will be used for documentation purpose and also naming variables and parameters in the source code. All names has the Python-like data type in brackets. + +The real Python types are implemented in [types.py](../bashi/types.py) - **parameter** (`str`): A `parameter` represents a software component like the host compiler or a specific software like `CMake` or `Boost`. A `parameter` names a list of `parameter-values` and expresses how a `parameter-value` is used. -- **parameter-value** (`Tuple[str, packaging.version.Version]`): A `parameter-value` represents of a specific version of a `parameter`, for example `GCC 10`, `nvcc 12.2` or `CMake 3.28`. The pair wise generator takes on `parameter-value` of each `parameter` for is combinatorics. +- **parameter-value** (`Tuple[value-name: str, value-version: packaging.version.Version]`): A `parameter-value` represents of a specific version of a `parameter`, for example `GCC 10`, `nvcc 12.2` or `CMake 3.28`. The pair wise generator takes on `parameter-value` of each `parameter` for is combinatorics. - **value-name** (`str`): The `value-name` is the first part of the `parameter-value`. It names a specific software component, like `GCC` or `CMake`. If the `parameter` names a specific software, `parameter` and `value-name` are equal. - **value-version** (`packaging.version.Version`): The `value-version` is the second part of the `parameter-value`. It defines a specific version of a software component such like `12.2` or `3.12`. -- **parameter-value-list** (`str=List[Tuple[str, packaging.version.Version]]`): A `parameter-value-list` is a list of `parameter-values` assigned to a `parameter`. For example: +- **parameter-value-list** (`parameter: str = List[parameter-value: Tuple[value-name: str, value-version: packaging.version.Version]]`): A `parameter-value-list` is a list of `parameter-values` assigned to a `parameter`. For example: - `HOST_COMPILER=[(GCC, 10), (GCC, 11), (CLANG, 16), (CLANG, 17)]` - `DEVICE_COMPILER=[(GCC, 10), (GCC, 11), (CLANG, 16), (CLANG, 17), (NVCC, 11.2), (NVCC, 12.0)]` - `CMAKE=[(CMAKE, 3.22), (CMAKE, 3.23), (CMAKE, 3.24)]` -- **parameter-value-matrix** (`OrderedDict[str, List[Tuple[str, packaging.version.Version]]]`): The `parameter-value-matrix` is a list of `parameter-value-list`s. The `parameter-value-matrix` is used as input for the pair-wise generator. The data type is `OrderedDict` because the order of `parameters` is important. -- **parameter-value-tuple** (`OrderedList[Tuple[str, packaging.version.Version]]`): A `parameter-value-tuple` is a list of one ore more `parameter-value`s. The `parameter-value-tuple` is created from a `parameter-value-matrix` and each `parameter-value` is assigned to a different `parameter`. This means, each `parameter-value` is from a different `parameter-value-list` in a `parameter-value-matrix`. The `parameter-value-tuple` has the same or a smaller number of entries as the number of `parameters` in a `parameter-value-matrix`. -- **combination** (`OrderedList[Tuple[str, packaging.version.Version]]`): A `combination` is a `parameter-value-tuple` with the same number of `parameter-value`s as the number of input `parameters`. -- **combination-list** (`List[OrderedList[Tuple[str, packaging.version.Version]]]`): A `combination-list` is a list of `combination`s an the result of the pair-wise generator. -- **parameter-value-pair** (`Tuple[Tuple[str, packaging.version.Version]], Tuple[str, packaging.version.Version]]]`): A `parameter-value-pair` is a `parameter-value-tuple` with exact two `parameter-values`. The pair-wise generator guaranties that each `parameter-value-pair`, which can be created by the given `parameter-value-matrix` exists at least in one `combination` of the `combination-list`. The only exception is, if a `parameter-value-pair` is forbidden by a filter rule. +- **parameter-value-matrix** (`OrderedDict[parameter: str, List[parameter-value: Tuple[value-name: str, value-version: packaging.version.Version]]]`): The `parameter-value-matrix` is a list of `parameter-value-list`s. The `parameter-value-matrix` is used as input for the pair-wise generator. The data type is `OrderedDict` because the order of `parameters` is important. +- **parameter-value-tuple** (`OrderedList[parameter: str, parameter-value: Tuple[value-name: str, value-version: packaging.version.Version]]`): A `parameter-value-tuple` is a list of one ore more `parameter-value`s. The `parameter-value-tuple` is created from a `parameter-value-matrix` and each `parameter-value` is assigned to a different `parameter`. This means, each `parameter-value` is from a different `parameter-value-list` in a `parameter-value-matrix`. The `parameter-value-tuple` has the same or a smaller number of entries as the number of `parameters` in a `parameter-value-matrix`. +- **combination** (`OrderedList[parameter: str, parameter-value: Tuple[value-name: str, value-version: packaging.version.Version]]`): A `combination` is a `parameter-value-tuple` with the same number of `parameter-value`s as the number of input `parameters`. +- **combination-list** (`List[OrderedList[parameter : str, parameter-value: Tuple[value-name: str, value-version: packaging.version.Version]]]`): A `combination-list` is a list of `combination`s an the result of the pair-wise generator. +- **parameter-value-pair** (`OrderedList[parameter: str, parameter-value: Tuple[value-name: str, value-version: packaging.version.Version]]`): A `parameter-value-pair` is a `parameter-value-tuple` with exact two `parameter-values`. The pair-wise generator guaranties that each `parameter-value-pair`, which can be created by the given `parameter-value-matrix` exists at least in one `combination` of the `combination-list`. The only exception is, if a `parameter-value-pair` is forbidden by a filter rule. diff --git a/pyproject.toml b/pyproject.toml index 8427f74..5f61a27 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -12,7 +12,7 @@ authors = [ {name = "Jan Stephan", email = "j.stephan@hzdr.de"}, ] readme = "README.md" -requires-python = ">=3.9" +requires-python = ">=3.10" license = {file = "LICENSE"} description = "The library provides everything needed to generate a sparse combination matrix for alpaka-based projects, including a set of general-purpose combination rules." dynamic = ["version"] diff --git a/tests/test_filter_adapter.py b/tests/test_filter_adapter.py index dcf4934..87a84e3 100644 --- a/tests/test_filter_adapter.py +++ b/tests/test_filter_adapter.py @@ -5,13 +5,14 @@ from packaging.version import Version import packaging.version as pkv from typeguard import typechecked +from bashi.types import ParameterValueTuple, ParameterValue from bashi.utils import FilterAdapter class TestFilterAdapterDataSet1(unittest.TestCase): @classmethod def setUpClass(cls): - cls.param_val_tuple: OrderedDict[str, Tuple[str, Version]] = OrderedDict() + cls.param_val_tuple: ParameterValueTuple = OrderedDict() cls.param_val_tuple["param1"] = ("param-val-name1", pkv.parse("1")) cls.param_val_tuple["param2"] = ("param-val-name2", pkv.parse("2")) cls.param_val_tuple["param3"] = ("param-val-name3", pkv.parse("3")) @@ -20,7 +21,7 @@ def setUpClass(cls): for index, param_name in enumerate(cls.param_val_tuple.keys()): cls.param_map[index] = param_name - cls.test_row: List[Tuple[str, Version]] = [] + cls.test_row: List[ParameterValue] = [] for param_val in cls.param_val_tuple.values(): cls.test_row.append(param_val) @@ -29,13 +30,13 @@ def setUpClass(cls): # isinstance() does not verify the key and value type def test_function_type(self): @typechecked - def filter_function(row: OrderedDict[str, Tuple[str, Version]]) -> bool: + def filter_function(row: ParameterValueTuple) -> bool: if len(row.keys()) < 1: raise AssertionError("There is no element in row.") # typechecked does not check the types of Tuple, therefore I "unwrap" it @typechecked - def check_param_value_type(_: Tuple[str, Version]): + def check_param_value_type(_: ParameterValue): pass check_param_value_type(next(iter(row.values()))) @@ -46,7 +47,7 @@ def check_param_value_type(_: Tuple[str, Version]): self.assertTrue(filter_adapter(self.test_row)) def test_function_length(self): - def filter_function(row: OrderedDict[str, Tuple[str, Version]]) -> bool: + def filter_function(row: ParameterValueTuple) -> bool: if len(row) != 3: raise AssertionError(f"Size of test_row is {len(row)}. Expected is 3.") @@ -56,7 +57,7 @@ def filter_function(row: OrderedDict[str, Tuple[str, Version]]) -> bool: self.assertTrue(filter_adapter(self.test_row)) def test_function_row_order(self): - def filter_function(row: OrderedDict[str, Tuple[str, Version]]) -> bool: + def filter_function(row: ParameterValueTuple) -> bool: excepted_param_order = ["param1", "param2", "param3"] if len(excepted_param_order) != len(row): raise AssertionError( @@ -104,7 +105,7 @@ def test_lambda(self): class TestFilterAdapterDataSet2(unittest.TestCase): @classmethod def setUpClass(cls): - cls.param_val_tuple: OrderedDict[str, Tuple[str, Version]] = OrderedDict() + cls.param_val_tuple: ParameterValueTuple = OrderedDict() cls.param_val_tuple["param6b"] = ("param-val-name1", pkv.parse("3.21.2")) cls.param_val_tuple["param231a"] = ("param-val-name67asd", pkv.parse("2.4")) cls.param_val_tuple["param234s"] = ("param-val-678", pkv.parse("3")) @@ -119,8 +120,8 @@ def setUpClass(cls): for param_val in cls.param_val_tuple.values(): cls.test_row.append(param_val) - def test_function_row_lenght_order(self): - def filter_function(row: OrderedDict[str, Tuple[str, Version]]) -> bool: + def test_function_row_length_order(self): + def filter_function(row: ParameterValueTuple) -> bool: excepted_param_order = ["param6b", "param231a", "param234s", "foo", "bar"] if len(excepted_param_order) != len(row): raise AssertionError(