Merge pull request #4 from SimeonEhrig/naming

define naming for bashi library

.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

README.md

@@ -8,6 +8,10 @@ This project will be the successor to the [alpaka-job-matrix-library](https://gi
 
 A library to provide a job generator for CI's for alpaka based projects.
 
+# Naming
+
+The main component of the `bashi` library is combinatorics. Due to the wide spread of the field, there are different words for the same things. Therefore, `bashi` has introduced a naming guideline that is used for function and parameter names and documentation. Please read the [naming guidelines](docs/naming.md).
+
 # Developing
 
 It is strongly recommended to use a Python environment for developing the code, such as `virtualenv` or a `conda` environment. The following code uses a `virtualenv`.

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]

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)

docs/naming.md

@@ -0,0 +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-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[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** (`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[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.

pyproject.toml

@@ -12,7 +12,7 @@ authors = [
     {name = "Jan Stephan", email = "[email protected]"}, 
 ]
 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"]

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(