baldertest 0.1.0__py3-none-any.whl

_balder/controllers/vdevice_controller.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+from typing import Type, Dict, Union
+
+import logging
+from _balder.vdevice import VDevice
+from _balder.feature import Feature
+from _balder.controllers.base_device_controller import BaseDeviceController
+from _balder.exceptions import VDeviceResolvingError
+
+logger = logging.getLogger(__file__)
+
+
+class VDeviceController(BaseDeviceController):
+    """
+    This is the controller class for :class:`VDevice` items.
+    """
+    # helper property to disable manual constructor creation
+    __priv_instantiate_key = object()
+
+    #: contains all existing VDevices and its corresponding controller object
+    _items: Dict[Type[VDevice], VDeviceController] = {}
+
+    def __init__(self, related_cls, _priv_instantiate_key):
+        super().__init__()
+
+        # this helps to make this constructor only possible inside the controller object
+        if _priv_instantiate_key != VDeviceController.__priv_instantiate_key:
+            raise RuntimeError('it is not allowed to instantiate a controller manually -> use the static method '
+                               '`VDeviceController.get_for()` for it')
+
+        if not isinstance(related_cls, type):
+            raise TypeError('the attribute `related_cls` has to be a type (no object)')
+        if not issubclass(related_cls, VDevice):
+            raise TypeError(f'the attribute `related_cls` has to be a sub-type of `{VDevice.__name__}`')
+        if related_cls == VDevice:
+            raise TypeError(f'the attribute `related_cls` is `{VDevice.__name__}` - controllers for native type are '
+                            f'forbidden')
+        # contains a reference to the related class this controller instance belongs to
+        self._related_cls = related_cls
+
+    # ---------------------------------- STATIC METHODS ----------------------------------------------------------------
+
+    @staticmethod
+    def get_for(related_cls: Type[VDevice]) -> VDeviceController:
+        """
+        This class returns the current existing controller instance for the given item. If the instance does not exist
+        yet, it will automatically create it and saves the instance in an internal dictionary.
+        """
+        if VDeviceController._items.get(related_cls) is None:
+            item = VDeviceController(related_cls, _priv_instantiate_key=VDeviceController.__priv_instantiate_key)
+            VDeviceController._items[related_cls] = item
+
+        return VDeviceController._items.get(related_cls)
+
+    # ---------------------------------- CLASS METHODS -----------------------------------------------------------------
+
+    # ---------------------------------- PROPERTIES --------------------------------------------------------------------
+
+    @property
+    def related_cls(self) -> Type[VDevice]:
+        return self._related_cls
+
+    # ---------------------------------- PROTECTED METHODS -------------------------------------------------------------
+
+    # ---------------------------------- METHODS -----------------------------------------------------------------------
+
+    def get_outer_class(self) -> Union[Type[Feature], None]:
+        """
+        This method delivers the outer class of this device. In Balder, this has to be a :class:`Feature`.
+        """
+        return getattr(self.related_cls, '_outer_balder_class', None)
+
+    def get_next_parent_vdevice(self) -> Union[Type[VDevice], None]:
+        """
+        This method returns the next parent VDevice class, which is still a subclass of :class:`VDevice`. If the next
+        parent class is :class:`VDevice`, None will be returned.
+
+        :return: the parent VDevice class or None if no parent exists
+        """
+        possible_vdevices_of_interest = []
+        for cur_vdevice_of_interest in self.related_cls.__bases__:
+            if issubclass(cur_vdevice_of_interest, VDevice) and cur_vdevice_of_interest != VDevice:
+                possible_vdevices_of_interest.append(cur_vdevice_of_interest)
+
+        if len(possible_vdevices_of_interest) > 1:
+            raise VDeviceResolvingError(
+                f"the vdevice `{self.related_cls.__name__}` has more than one parent classes from type "
+                f"`VDevice` - this is not allowed")
+
+        if len(possible_vdevices_of_interest) == 1:
+            # we have found one parent vDevice that has the same name as the cur_vdevice
+            return possible_vdevices_of_interest[0]
+
+        # we have no parent vDevice -> there are no parent ConnectionTree
+        return None

_balder/decorator_connect.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+from typing import Type, Union
+
+import re
+from _balder.device import Device
+from _balder.connection import Connection
+from _balder.controllers import DeviceController
+from _balder.cnnrelations import AndConnectionRelation, OrConnectionRelation
+
+
+def connect(
+        with_device: Union[Type[Device], str],
+        over_connection: Union[Connection, Type[Connection], AndConnectionRelation, OrConnectionRelation],
+        self_node_name: str = None,
+        dest_node_name: str = None
+):
+    """
+    This decorator connects two devices with each other. It can be used for scenarios as well as setup devices.
+
+    :param with_device: that's the :class:`Device` that should be connected to the decorated device
+
+    :param over_connection: that's the connection tree that should connect the devices with each other
+
+    :param self_node_name: the node name of this device (if this param is not given, balder automatically generates a
+                           new node name in format `n{unique device counter}`)
+
+    :param dest_node_name: the node name of the destination device, given with `with_device` (if this param is not
+                           given, balder automatically generates a new node name in format `n{unique device counter}`)
+    """
+    allowed_regex_auto_node_names = r"n[0-9]+"
+
+    if not isinstance(with_device, str) and not issubclass(with_device, Device):
+        raise ValueError("the value of `with_device` must be a `Device` (or a subclass thereof) or the device name "
+                         "as a string")
+    if isinstance(over_connection, type):
+        if not issubclass(over_connection, Connection):
+            raise TypeError("the type of `over_connection` must be a `Connection` (or a subclass of it)")
+    elif not isinstance(over_connection, Connection):
+        raise TypeError("the type of `over_connection` must be a `Connection` (or a subclass of it)")
+
+    if self_node_name is not None:
+        if not isinstance(self_node_name, str):
+            raise TypeError("the type of `node_name` must be a `str`")
+        if re.match(allowed_regex_auto_node_names, self_node_name):
+            raise ValueError(
+                f"the given `self_node_name` matches the regular expression `{allowed_regex_auto_node_names}` that is "
+                f"reserved for internal node naming and should not be used by you")
+    if dest_node_name is not None:
+        if not isinstance(dest_node_name, str):
+            raise TypeError("the type of `node_name` must be a `str`")
+        if re.match(allowed_regex_auto_node_names, dest_node_name):
+            raise ValueError(
+                f"the given `dest_node_name` matches the regular expression `{allowed_regex_auto_node_names}` that is "
+                f"reserved for internal node naming and should not be used by you")
+
+    class MyDecorator:
+        """
+        This decorator will add the connection to the device that is decorated. If the `with_device` is no other device
+        class (given as string) this decorator can not handle the node allocation and the device resolving (because not
+        all devices are resolved yet). In this case the function adds the device-string in the :class:`Connection`
+        object and if the `dest_node_name` is None, it will also set this value to None. This secure that the
+        collector will create a unique auto node for it.
+        """
+        def __new__(cls, *args, **kwargs):  # pylint: disable=unused-argument
+
+            decorated_cls = args[0]
+            nonlocal with_device
+            nonlocal over_connection
+            nonlocal self_node_name
+            nonlocal dest_node_name
+
+            this_outer_ref = decorated_cls.__qualname__.split('.')[:-1]
+            if not isinstance(with_device, str):
+                other_outer_ref = with_device.__qualname__.split('.')[:-1]
+                if this_outer_ref != other_outer_ref:
+                    raise ValueError(
+                        f"the given device is not mentioned in this setup/scenario - please create a new "
+                        f"direct inner device class, it can be inherited from `{with_device.__qualname__}`")
+            decorated_cls_device_controller = DeviceController.get_for(decorated_cls)
+
+            # if required give auto name to nodes
+            if self_node_name is None:
+                self_node_name = decorated_cls_device_controller.get_new_empty_auto_node()
+            if dest_node_name is None and not isinstance(with_device, str):
+                with_device_controller = DeviceController.get_for(with_device)
+                dest_node_name = with_device_controller.get_new_empty_auto_node()
+
+            cur_cnn_instance = None
+            if isinstance(over_connection, Connection):
+                # already instantiated because it comes back from a `based_on` - clone it to secure that it was not used
+                #  in another `@connect()` decorator (and also remove possible metadata from the new clone)
+                cur_cnn_instance = over_connection.clone()
+                cur_cnn_instance.set_metadata_for_all_subitems(None)
+            elif isinstance(over_connection, type) and issubclass(over_connection, Connection):
+                # not instantiated -> instantiate it
+                cur_cnn_instance = over_connection()
+            elif isinstance(over_connection, (AndConnectionRelation, OrConnectionRelation)):
+                over_connection = Connection.based_on(over_connection)
+            cur_cnn_instance.metadata.set_from(from_device=decorated_cls, from_device_node_name=self_node_name)
+            cur_cnn_instance.metadata.set_to(to_device=with_device, to_device_node_name=dest_node_name)
+
+            decorated_cls_device_controller.add_new_raw_connection(cur_cnn_instance)
+            return decorated_cls
+    return MyDecorator

_balder/decorator_covered_by.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+from typing import Type, Union
+
+import inspect
+
+from _balder.controllers import ScenarioController
+from _balder.scenario import Scenario
+
+
+def covered_by(item: Union[Type[Scenario], str, callable, None]):
+    """
+    This decorator defines that there exists another Scenario class or test method item that has a similar
+    implementation like the decorated :class:`Scenario` class or the decorated test method.
+
+    :param item: the element which contains the whole implementation of this scenario or test method
+    """
+
+    if item is None:
+        pass
+    elif isinstance(item, str) and item.startswith("test_"):
+        pass
+    elif callable(item) and inspect.isfunction(item) and item.__name__.startswith("test_"):
+        pass
+    elif isinstance(item, type) and issubclass(item, Scenario):
+        raise NotImplementedError('The covered-by other scenario classes is not supported yet')
+    else:
+        raise TypeError("the given element for `item` must be a test method of a scenario class (has to start with "
+                        "`test_`)")
+
+    class CoveredByDecorator:
+        """decorator class for `@covered_by` decorator"""
+        def __init__(self, func):
+            self.func = func
+
+            if inspect.isclass(func):
+                # it must be a class decorator
+                if not issubclass(func, Scenario):
+                    raise TypeError(f"The decorator `@covered_by` may only be used for `Scenario` objects or for test "
+                                    f"methods of one `Scenario` object. This is not possible for the applied class "
+                                    f"`{func.__name__}`.")
+                raise NotImplementedError('The covered-by decoration of other scenario classes is not supported yet')
+                # scenario_controller = ScenarioController.get_for(func)
+                # register for the whole class
+                # scenario_controller.register_covered_by_for(meth=None, covered_by=item)
+            if inspect.isfunction(func):
+                # work will done in `__set_name__`
+                pass
+            else:
+                raise TypeError(f"The use of the `@covered_by` decorator is not allowed for the `{str(func)}` element. "
+                                f"You should only use this decorator for test method elements of a `Scenario` object")
+
+        def __set_name__(self, owner, name):
+            if issubclass(owner, Scenario):
+                if not inspect.isfunction(self.func):
+                    raise TypeError("the use of the `@covered_by` decorator is only allowed for test methods of "
+                                    "`Scenario` objects")
+                if not name.startswith('test_'):
+                    raise TypeError(f"the use of the `@covered_by` decorator is only allowed for test methods of "
+                                    f"`Scenario` objects - the method `{owner.__name__}.{name}` does not start with "
+                                    f"`test_` and is not a valid test method")
+                # if item is a string - resolve method
+                cleared_item = item
+                if isinstance(item, str):
+                    cleared_item = getattr(owner, item)
+                scenario_controller = ScenarioController.get_for(owner)
+                scenario_controller.register_covered_by_for(meth=name, covered_by=cleared_item)
+            else:
+                raise TypeError(f"The use of the `@covered_by` decorator is not allowed for methods of a "
+                                f"`{owner.__name__}`. You should only use this decorator for valid test methods of a "
+                                f"`Scenario` object")
+
+            setattr(owner, name, self.func)
+
+    return CoveredByDecorator

_balder/decorator_fixture.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from typing import Literal
+
+import functools
+from _balder.collector import Collector
+from _balder.fixture_execution_level import FixtureExecutionLevel
+
+
+def fixture(level: Literal['session', 'setup', 'scenario', 'variation', 'testcase']):
+    """
+    This decorator declares the decorated function/method as a fixture function/method.
+
+    :param level: the execution level the fixture should have
+    """
+    allowed_levels = [level.value for level in FixtureExecutionLevel]
+
+    if level not in allowed_levels:
+        raise ValueError(f"the value of `level` must be a `str` with one of the values `{'`, `'.join(allowed_levels)}`")
+
+    def decorator_fixture(func):
+        # always register the raw fixture in Collector - class determination will be done later by :meth:`Collector`
+        Collector.register_raw_fixture(func, level)
+
+        @functools.wraps(func)
+        def wrapper_fixture(*args, **kwargs):
+            func(*args, **kwargs)
+
+        return wrapper_fixture
+    return decorator_fixture

_balder/decorator_for_vdevice.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+from typing import Union, Type
+
+import inspect
+from _balder.cnnrelations import AndConnectionRelation, OrConnectionRelation
+from _balder.collector import Collector
+from _balder.feature import Feature
+from _balder.vdevice import VDevice
+from _balder.connection import Connection
+from _balder.controllers import FeatureController
+from _balder.exceptions import DuplicateForVDeviceError, UnknownVDeviceException
+
+
+def for_vdevice(
+        vdevice: Union[str, Type[VDevice]],
+        with_connections: Union[
+            Type[Connection], Connection, AndConnectionRelation, OrConnectionRelation
+        ] = Connection(),
+):
+    """
+    With the `@for_vdevice` you can limit the decorated object for a special allowed connection tree for every existing
+    vDevice. This decorator can be used to decorate whole :class:`Feature` classes just like single methods of a
+    :class:`Feature` class.
+
+    Decorated Feature classes: This controls the allowed sub-connection tree between the mapped device of the given
+                               vDevice and the device class that uses the decorated feature. If the defined sub-tree
+                               does not match the sub-tree that connects the both devices with each other on the setup
+                               level, the feature can not be applied.
+
+    Decorated Feature method: Similar to the class based decoration, you can specify if a method is executable with
+                              the given sub-tree. Especially, at this point you are able to define your own method
+                              variations. Balder will select the chosen one depending on the matching connection
+                              sub-tree.
+
+    You can find more about this in the documentation chapter :ref:`VDevices and method-variations`.
+
+    :param vdevice: the vDevice this decorator should describe
+
+    :param with_connections: the assigned connection trees for this class/method (default: a universal connection)
+    """
+    if isinstance(with_connections, Connection):
+        # do nothing
+        pass
+    elif isinstance(with_connections, (AndConnectionRelation, OrConnectionRelation)):
+        # use container connection
+        with_connections = Connection.based_on(with_connections)
+    elif isinstance(with_connections, type) and issubclass(with_connections, Connection):
+        # instantiate it
+        with_connections = with_connections()
+    else:
+        raise TypeError(f"the given element ``with_connection`` needs to be from type `AndConnectionRelation`, "
+                        f"`OrConnectionRelation` or `Connection` - `{type(with_connections)}` is not allowed")
+
+    # note: if `args` is an empty list - no special sub-connection-tree bindings
+
+    if not (isinstance(vdevice, str) or (isinstance(vdevice, type) and issubclass(vdevice, VDevice))):
+        raise ValueError('the given element for `vdevice` has to be a `str` or has to be a subclass of'
+                         '`VDevice`')
+
+    class ForVDeviceDecorator:
+        """decorator class for `@for_vdevice` decorator"""
+
+        def __init__(self, func):
+            nonlocal vdevice
+            nonlocal with_connections
+
+            self.func = func
+
+            # we detect a decorated non-class object -> save it and check it later in collector
+            Collector.register_possible_method_variation(func, vdevice, with_connections)
+
+        def __new__(cls, *args, **kwargs):  # pylint: disable=unused-argument
+            nonlocal vdevice
+
+            func = args[0]
+
+            if inspect.isclass(func):
+                # it must be a class decorator
+                if not issubclass(func, Feature):
+                    raise TypeError(f"The decorator `@for_vdevice` may only be used for `Feature` objects. This is "
+                                    f"not possible for the applied class `{func.__name__}`.")
+
+                fn_feature_controller = FeatureController.get_for(func)
+
+                if isinstance(vdevice, str):
+                    # vDevice is a string, so we have to convert it to the correct class
+                    relevant_vdevices = [cur_vdevice for cur_vdevice
+                                         in fn_feature_controller.get_abs_inner_vdevice_classes()
+                                         if cur_vdevice.__name__ == vdevice]
+
+                    if len(relevant_vdevices) == 0:
+                        raise ValueError(
+                            f"can not find a matching inner VDevice class for the given vDevice string `{vdevice}` in "
+                            f"the feature class `{func.__name__}`")
+
+                    if len(relevant_vdevices) > 1:
+                        raise RuntimeError("found more than one possible vDevices - something unexpected happened")
+
+                    vdevice = relevant_vdevices[0]
+                cls_for_vdevice = fn_feature_controller.get_class_based_for_vdevice()
+                if vdevice in cls_for_vdevice.keys():
+                    raise DuplicateForVDeviceError(
+                        f'there already exists a decorator for the vDevice `{vdevice}` in the Feature class '
+                        f'`{func.__name__}`')
+                if vdevice not in fn_feature_controller.get_abs_inner_vdevice_classes():
+                    raise UnknownVDeviceException(
+                        f"the given vDevice `{vdevice}` is no usable vDevice in Feature class `{func.__name__}`")
+
+                cls_for_vdevice[vdevice] = with_connections
+                fn_feature_controller.set_class_based_for_vdevice(cls_for_vdevice)
+                # directly return the class -> we do not want to manipulate it
+                return func
+
+            # otherwise, work will be done in `__init__`
+            # return this decorator object to work with
+            return super().__new__(ForVDeviceDecorator)
+
+    return ForVDeviceDecorator

_balder/decorator_gateway.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from _balder.controllers.device_controller import DeviceController
+from _balder.device import Device
+from _balder.node_gateway import NodeGateway
+
+
+def gateway(from_node: str, to_node: str, bidirectional: bool = True):
+    """
+    This decorator enables two nodes of a device to be connected to one another via a gateway. The gateway can
+    implement an unidirectional or bidirectional connection.
+    """
+    if not isinstance(from_node, str) and not isinstance(to_node, str):
+        raise ValueError("the value of `from_node` and `to_node` must be the name of the nodes (type `str`)")
+
+    if isinstance(bidirectional, bool):
+        raise ValueError("the value of `bidirectional` must be a `bool`")
+
+    def decorator(cls):
+        nonlocal from_node
+        nonlocal to_node
+        nonlocal bidirectional
+
+        # it must be a class decorator
+        if not issubclass(cls, Device):
+            raise TypeError(
+                f"The decorator `gateway` may only be used for `Device` objects. This is not possible for the applied "
+                f"class `{cls.__name__}`.")
+        decorated_cls_device_controller = DeviceController.get_for(cls)
+
+        new_gateway = NodeGateway(cls, from_node, to_node, bidirectional)
+        decorated_cls_device_controller.add_new_raw_gateway(new_gateway)
+        return cls
+    return decorator

_balder/decorator_insert_into_tree.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+from typing import Type, Union, List, Tuple
+
+from _balder.connection import Connection
+
+
+def insert_into_tree(parents: List[Union[Type[Connection], Tuple[Type[Connection]]]] = None, tree_name: str = ""):
+    """
+    This decorator inserts a :meth:`Connection` object into the global connection tree.
+
+    :param parents: all items that are parents of the decorated connection
+
+    :param tree_name: the tree name the connection should be inserted in
+    """
+    if parents is None:
+        parents = []
+    if not isinstance(parents, list):
+        raise ValueError("the value of `parents` must be a `list`")
+
+    idx = 0
+    for cur_parent in parents:
+        if isinstance(cur_parent, tuple):
+            tuple_idx = 0
+            for cur_tuple_element in cur_parent:
+                if not isinstance(cur_tuple_element, type) or not issubclass(cur_tuple_element, Connection):
+                    raise TypeError(
+                        f"the tuple element on index {tuple_idx} (located on index {idx} of `parents`)  must be a "
+                        f"`Connection` type (given element is: {str(cur_parent)})")
+                tuple_idx += 1
+        else:
+            if not isinstance(cur_parent, type) or not issubclass(cur_parent, Connection):
+                raise TypeError(
+                    f"the element on index {idx} in `parents` must be a `Connection` type (given: {str(cur_parent)})")
+        idx += 1
+
+    class MyDecorator:
+        """decorator class for `@insert_into_tree` decorator"""
+        def __new__(cls, *args, **kwargs):  # pylint: disable=unused-argument
+
+            nonlocal parents
+
+            decorated_cls = args[0]
+
+            conn_parents = decorated_cls.get_parents(tree_name=tree_name)
+            conn_parents = [] if conn_parents is None else conn_parents
+
+            conn_parents += [new_parent for new_parent in parents if new_parent not in conn_parents]
+            decorated_cls.set_parents(conn_parents, tree_name=tree_name)
+
+            return decorated_cls
+
+    return MyDecorator

_balder/decorator_parametrize.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from typing import Iterable, Any
+
+import inspect
+from _balder.collector import Collector
+
+
+def parametrize(
+        field_name: str,
+        values: Iterable[Any],
+):
+    """
+    Allows to parametrize a test function. This decorator will be used to statically parametrize a test function.
+
+    :param field_name: the field name of the test function
+
+    :param values: an iterable of values, that should be used to parametrize the test function
+    """
+    if not isinstance(field_name, str):
+        raise ValueError('the given field name must be a string')
+
+    def decorator(func):
+        nonlocal field_name
+        nonlocal values
+
+        if not inspect.isfunction(func):
+            raise TypeError('the decorated object needs to be a test method')
+
+        Collector.register_possible_parametrization(func, field_name, values)
+        return func
+    return decorator

_balder/decorator_parametrize_by_feature.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+from typing import Dict, Tuple, Type
+
+import inspect
+from _balder.collector import Collector
+from _balder.device import Device
+from _balder.parametrization import FeatureAccessSelector, Parameter, Value
+
+
+def parametrize_by_feature(
+        field_name: str,
+        feature_accessor: Tuple[Type[Device], str, str],
+        parameter: Dict[str, FeatureAccessSelector | Parameter | Value] = None
+):
+    """
+    Allows to parametrize a test function. This decorator will be used to dynamically parametrize a test function, by
+    the value a setup feature returns before entering the test.
+
+    :param field_name: the field name of the test function
+    :param feature_accessor: a tuple that provides information for accessing the feature
+    :param parameter: the parameter to parametrize the feature method (if necessary)
+    """
+    if not isinstance(field_name, str):
+        raise ValueError('the given field name must be a string')
+    if parameter is None:
+        parameter = {}
+
+    feature_accessor = FeatureAccessSelector(*feature_accessor, parameters=parameter)
+
+    def decorator(func):
+        if not inspect.isfunction(func):
+            raise TypeError('the decorated object needs to be a test method')
+
+        Collector.register_possible_parametrization(func, field_name, feature_accessor)
+        return func
+    return decorator

_balder/device.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+
+class Device:
+    """
+    This is the basic device class. It represents an abstract class that should not be used directly. Every inner device
+    has to inherit from this class.
+    """
+
+    # ---------------------------------- STATIC METHODS ----------------------------------------------------------------
+
+    # ---------------------------------- CLASS METHODS ----------------------------------------------------------------
+
+    # ---------------------------------- PROPERTIES --------------------------------------------------------------------
+
+    # ---------------------------------- PROTECTED METHODS -------------------------------------------------------------
+
+    # ---------------------------------- METHODS -----------------------------------------------------------------------