Controllers API

Controller are objects, that provides different methods to manage important Balder objects like Device, Scenario, Setup or Feature objects.

Controller objects are only relevant if you want to modify the behavior of Balder or sometimes if you want to work with the plugin engine. In the most cases you have not to interact with controllers.

Basic Controller

class _balder.controllers.Controller

This is the base controller class. It serves as a base class for all other specialized controllers.

A controller is used to manage the behavior internally.

abstract static get_for(related_cls)

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.

abstract property related_cls

This method returns the related class that belongs to that controller.

Scenario/Setup Controller

class _balder.controllers.NormalScenarioSetupController

This is the abstract base controller class for the Scenario- and Setup-Controller.

check_vdevice_feature_existence()

This method validates that the Feature property set of a Device holds all required Feature objects of the related VDevice. For this the method checks that every feature (that is used in a mapped VDevice) also exists as a child Feature property in the related Device class.

Note

Variations are not related to this and will not be checked here.

determine_raw_absolute_device_connections()

This method determines and creates the basic _absolute_connections for the related scenario/setup. Note, that this method only creates the class attribute and adds the synchronized connections (same on both sides if they are bidirectional). It does not analyse or take Feature classes into consideration.

get_abs_inner_device_class_by_string(device_str: str) → Optional[Type[_balder.device.Device]]

This method returns the absolute inner Device class for the given string.

Parameters

device_str – the name string of the Device that should be returned

Returns

the Device class or None, if the method has not found any class with this name

get_absolute_single_connections() → Dict[Type[Device], Dict[str, Dict[Type[Device], Dict[str, List[Connection]]]]]

This method determines the synchronized (both devices of a connection were updated) absolute connections between all devices of this scenario/setup.

Returns

returns a dictionary which provides all single connections between two devices that can be accessed with result[dev1][node-of-dev1][dev2][node-of-dev2]

get_all_abs_connections() → List[Connection]

This method returns all absolute connection objects which have been defined between absolute devices of the related scenario or setup class.

get_all_abs_inner_device_classes() → List[Type[_balder.device.Device]]

This method provides a list of all Device() classes that are valid for the related scenario or setup class. If the class itself does not implement some inner devices by its own, it returns the absolute inner devices of the next higher setup/scenario parent class.

get_all_connections() → List[Connection]

This method returns all connection objects which have been defined between devices of the related class.

get_all_inner_device_classes() → List[Type[_balder.device.Device]]

This method provides a list of all Device() classes that have been defined as inner classes in the related scenario or setup.

static get_for(related_cls) → Union[ScenarioController, SetupController]

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.

Note

This method automatically returns the correct controller type, depending on the class you provide with related_cls.

get_inner_device_class_by_string(device_str: str) → Optional[Type[_balder.device.Device]]

This method returns the inner Device class for the given string.

Parameters

device_str – the name string of the Device that should be returned

Returns

the Device class or None, if the method has not found any class with this name

abstract get_next_parent_class() → Optional[Union[Type[_balder.scenario.Scenario], Type[_balder.setup.Setup]]]

This method returns the next parent class which is a subclass of the Scenario/Setup itself.

Returns

returns the next parent class or None if the next parent class is Scenario/Setup itself

validate_inheritance()

This method validates that the inheritance of the related Setup/Scenario class was done correctly. It checks that all inner devices that are inherited has the same naming as their parents and also that every reused name (that is already be used for a device in the parent class) does also inherit from this parent scenario/setup device.

In addition to that, it secures that either all devices are overwritten in the current class or no devices are overwritten in the related class.

class _balder.controllers.ScenarioController(related_cls, _priv_instantiate_key)

This is the controller class for Scenario items.

determine_absolute_device_connections()

This method determines the real possible Sub-Connections for every element of the scenarios. For this the method will create a possible intersection connection, for the :class:´Connection´ between two devices and all Connection-Subtrees that are allowed for the mapped vDevices in the used Feature classes. The data will be saved in the Device property _absolute_connections. If the method detects an empty intersection between two devices that are connected through a VDevice-Device mapping, the method will throw an exception.

get_all_test_methods() → List[callable]

This method returns all test methods that were defined in the related scenario. A testmethod has to start with test_*.

get_feature_cleaned_absolute_single_connections() → Tuple[Dict[Type[_balder.device.Device], Dict[str, Dict[Type[_balder.device.Device], Dict[str, List[_balder.connection.Connection]]]]], Dict[Tuple[_balder.device.Device, _balder.device.Device], List[_balder.connection.Connection]]]

This method returns all absolute-single connections between all devices of this scenario, but already cleaned based on the cumulated class-based decorators of all the feature devices.

Note

Please note, that the reduction candidates connections do not have to be unique.

Returns

returns a tuple with the cleaned up connections (sorted as dictionary per device) and the reduced connections as second element

static get_for(related_cls: Type[_balder.scenario.Scenario]) → _balder.controllers.scenario_controller.ScenarioController

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.

get_next_parent_class() → Optional[Type[_balder.scenario.Scenario]]

This method returns the next parent class which is a subclass of the Scenario itself.

Returns

returns the next parent class or None if the next parent class is Scenario itself

property related_cls: Type[_balder.scenario.Scenario]

This method returns the related class that belongs to that controller.

validate_feature_clearance_for_parallel_connections()

This method validates for every active class-based feature (only the ones that have an active VDevice<->Device mapping), that there exist a clear scenario-device-connection for this feature. The method throws an UnclearAssignableFeatureConnectionError if there exists more than one possible device-connection for the related devices and the method is not able to determine a clear connection.

class _balder.controllers.SetupController(related_cls, _priv_instantiate_key)

This is the controller class for Setup items.

static get_for(related_cls: Type[_balder.setup.Setup]) → _balder.controllers.setup_controller.SetupController

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.

get_next_parent_class() → Optional[Type[_balder.setup.Setup]]

This method returns the next parent class which is a subclass of the Setup itself.

Returns

returns the next parent class or None if the next parent class is Setup itself

property related_cls: Type[_balder.setup.Setup]

This method returns the related class that belongs to that controller.

validate_feature_possibility()

This method validates that every feature connection (that already has a vDevice<->Device mapping on setup level) has a connection that is CONTAINED-IN the connection of the related setup devices.

Device controller

class _balder.controllers.BaseDeviceController

This is the abstract controller class for Device items.

get_all_instantiated_feature_objects() → Dict[str, _balder.feature.Feature]

This method returns all instantiated Feature() classes that were defined as static attributes within the related device.

Returns

supplies a dictionary with the name of the attribute as key and the current feature class as value

get_original_instanced_feature_objects() → Dict[str, _balder.feature.Feature]

This method returns the original instanced feature objects of the related device

abstract get_outer_class() → Union[Type[Scenario], Type[Setup], None]

This method delivers the outer class of this device. This has to be a Setup() or a Scenario().

save_all_original_instanced_features()

This property sets the internal dictionary about the original instantiated features of this Device/VDevice. This is done, to ensure that balder has saved an original copy of the original instantiated abstract features. The real features will be overwritten for each new variation by the ExecutorTree!

class _balder.controllers.DeviceController(related_cls, _priv_instantiate_key)

This is the main device controller to manage Device classes.

property absolute_connections: Dict[Type[Device], List[Connection]]

returns the absolute and SYNCHRONIZED connections between the related device and all other devices

add_new_absolute_connection(connection: Connection)

This method adds a new absolute connection to the internal property absolute_connections.

Note

This method doesn’t secure any synchronizing, it only sets the connection internally.

Note

It only adds a connection, if it does not already exist in the internal list - duplicates will not be added.

Parameters

connection – the connection object (the related device has to be part of it)

add_new_raw_connection(connection: Connection)

This method adds a new raw connection to the internal property connections.

Parameters

connection – the connection object (the related device has to be part of it)

cleanup_absolute_connections_with(other_device)

This method removes all connections from the related device to the given other_device.

property connections: Dict[str, List[Connection]]

returns the defined connections for the related devices (sorted after node name) - NOT SYNCHRONIZED - direct decorator values

get_all_absolute_connections() → Dict[str, List[Connection]]

This method returns all available absolute connection objects for the related device, sorted accordingly to their node name. Absolute connection are the cleaned connections, that are reduced to work with all used Feature and their VDevice classes.

The method also gets all possible connection objects from the outer class and sorts the relevant ones. The method detects connections from other devices of the outer class that starts or ends here, too.

Returns

returns a mapping between the node name and a list of Connection objects that belongs to the node

get_all_connections() → Dict[str, List[Connection]]

This method returns all available connection objects for the related device, sorted accordingly to their node name. The method gets all possible connection objects from the outer class (the setup or the scenario) and sorts the relevant ones.

The method detects connections from other devices of the outer class that starts or ends at the related device, too.

Returns

returns a mapping between the node name and a list of Connection objects that belongs to the node

static get_for(related_cls: Type[_balder.device.Device]) → _balder.controllers.device_controller.DeviceController

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.

get_new_empty_auto_node() → str

This helper method returns a new empty node name. This method can be used if balder should manage node names automatically.

get_next_parent_class() → Optional[Type[_balder.device.Device]]

This method returns the next parent class which is a subclass of the Device itself.

Returns

returns the next parent class or None if the next parent class is Device itself

get_node_types() → Dict[str, List[Connection, Tuple[Connection]]]

This method returns a dictionary with the node name as key and a connection class as value. This class describes the common connection sub-tree, that all incoming and outgoing connections of the related device have in common.

Raises

MultipleNodeBaseException – is thrown if the method finds several unrelated connections as a basis

get_outer_class() → Optional[Union[Type[_balder.scenario.Scenario], Type[_balder.setup.Setup]]]

This method delivers the outer class of the related device. This has to be a Setup or a Scenario.

property related_cls: Type[_balder.device.Device]

the related device type

resolve_connection_device_strings()

This method ensures that device names, that are provided as strings within connections between the current device and another device (which is given as string), are resolved. Since the @connect marker makes it possible to specify the other device as a string, this method will exchange these strings with the related device class.

Note

This is required, because in some cases you have to provide the devices for the decorator as a string, because the outer class could be imported later than the execution of the decorator was done. After Balder has read all files, all required information are available and this method should be able to resolve the device-strings.

resolve_mapped_vdevice_strings()

This method updates the inner VDevice-Device mappings for every instantiated Feature, if the mapped device (value in constructor) was given as a string. It secures that this device has a real VDevice reference for its mapped VDevice.

validate_inheritance_of_instantiated_features()

This method validates instantiated features and check that they are inherited correctly. It checks that the feature of a child device is also a child class of the feature of the parent device (in case they use the same property name).

validate_inner_referenced_features()

This method validates that every Feature that is referenced from another Feature of this device also exists in the definition list of this device.

class _balder.controllers.VDeviceController(related_cls, _priv_instantiate_key)

This is the controller class for VDevice items.

static get_for(related_cls: Type[_balder.vdevice.VDevice]) → _balder.controllers.vdevice_controller.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.

get_next_parent_vdevice() → Optional[Type[_balder.vdevice.VDevice]]

This method returns the next parent VDevice class, which is still a subclass of VDevice. If the next parent class is VDevice, None will be returned.

Returns

the parent VDevice class or None if no parent exists

get_outer_class() → Optional[Type[_balder.feature.Feature]]

This method delivers the outer class of this device. In Balder, this has to be a Feature.

property related_cls: Type[_balder.vdevice.VDevice]

This method returns the related class that belongs to that controller.

Feature controller

class _balder.controllers.FeatureController(related_cls, _priv_instantiate_key)

This is the controller class for Feature items.

determine_absolute_class_based_for_vdevice(print_warning)

This method determines the absolute class based @for_vdevice value for the related feature.

First it checks if there is a direct class based @for_vdevice decorator for this feature. It will not change anything, if the value was already set by an explicit class based @for_vdevice decorator. In this case the method only checks that every given vDevice class is a real part of the current Feature class (will be returned by direct call of method Feature.get_inner_vdevice_classes()). Otherwise, it determines the class based @for_vdevice value through analysing of the method based decorators and sets this determined value. If the method has to determine the value, it throws a warning with a suggestion for a nice class based decorator. Also, here the method will analyse the given vDevice classes and secures that they are defined in the current Feature class.

Note

This method automatically updates the values for the parent classes, too. Every time it searches for the values it considers the parent values for the vDevice or the parent class of the vDevice, too.

Note

This method can throw a user warning (throw_warning has to be True for that), but only on the given list of Feature classes. All parent Feature classes will be determined correctly, but will not throw a waring.

get_abs_class_based_for_vdevice() → Dict[Type[_balder.vdevice.VDevice], List[_balder.connection.Connection]]

This method returns the absolute calculated class-based-for-vdevice data for this feature.

get_abs_inner_vdevice_classes() → List[Type[_balder.vdevice.VDevice]]

This is a method that determines the inner VDevice classes for the feature class. If the method can not find some VDevices in the related feature class it also starts searching in the base classes. It always returns the first existing definition in the relevant parent classes.

get_active_method_variation(method_name: str) → Union[Tuple[Type[_balder.vdevice.VDevice], _balder.connection.Connection, Callable], Tuple[None, None, None]]

This method returns the current active method variation for the given method_name for the related fixture.

Note

Please note, this method only returns the set active method variation for this related feature only. It does not check parent classes of this feature.

Parameters

method_name – the name of the method the current active method variation should be returned

Returns

a tuple with the current active method selection or a tuple with None if no active method variation exists on this feature class level

get_class_based_for_vdevice() → Optional[Dict[Type[_balder.vdevice.VDevice], List[_balder.connection.Connection]]]

This method returns the class based data for the @for_vdevice decorator or None, if there is no decorator given

static get_for(related_cls: Type[_balder.feature.Feature]) → _balder.controllers.feature_controller.FeatureController

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.

get_inherited_method_variation(parent_class: Type[_balder.feature.Feature], method_var_name: str)

This method will determine the correct inherited method-variation for the current object. For this, it searches in the base classes of the given parent_class (which has to be a parent class of self) for the method-variation that should be called. It automatically detects if the parent class has a method-variation or is a single normal method. In case that the method is a single normal method, it will directly return it, otherwise it searches the correct method-variation according to the vDevice mapping of the current object and return the current active method-variation.

Parameters

• parent_class – the parent class of this object, the method should start searching for the method_var_name method (it searches in this class and all parents)

• method_var_name – the name of the method or of the method variation that should be returned

get_inner_referenced_features() → Dict[str, _balder.feature.Feature]

This method returns a dictionary with all referenced Feature objects, where the variable name is the key and the instantiated object the value.

get_inner_vdevice_class_by_string(device_str: str) → Optional[Type[_balder.vdevice.VDevice]]

This method returns the inner VDevice class for the given string.

Parameters

device_str – the name string of the VDevice that should be returned

Returns

the VDevice class or None, if the method has not found any class with this name

get_inner_vdevice_classes() → List[Type[_balder.vdevice.VDevice]]

This is a method that determines the inner VDevice classes for the related feature class. If the method can not find some VDevices in the current class it returns an empty list. This method will never search in parent classes.

If you want to get the absolute VDevices use Feature.get_inner_vdevice_classes().

get_method_based_for_vdevice() → Optional[Dict[str, Dict[Callable, Dict[Type[_balder.vdevice.VDevice], List[_balder.connection.Connection]]]]]

This method returns the method based data for the @for_vdevice decorator or None, if there is no decorator given

get_method_variation(of_method_name: str, for_vdevice: Type[_balder.vdevice.VDevice], with_connection: Union[_balder.connection.Connection, Tuple[_balder.connection.Connection]], ignore_no_findings: bool = False) → Optional[Callable]

This method searches for the unique possible method variation and returns it. In its search, the method also includes the parent classes of the related feature element of this controller.

Note

The method throws an exception if it can not find a valid unique method variation for the given data.

Note

Note, that the method does not check if the method name, the VDevice nor the given connection is really a part of this object. Please secure that the data is validated before.

Note

The method determines all possible method-variations. If it finds more than one clear method variation it tries to sort them hierarchical. This is done by checking if one possible method variation is contained in the other. If this can be clearly done, the method returns the furthest out one. Otherwise, it throws an UnclearMethodVariationError

Parameters

• of_method_name – the name of the method that should be returned

• for_vdevice – the VDevice that is mapped

• with_connection – the connection that is used between the device that uses the related feature and the VDevice

• ignore_no_findings – if this attribute is true, the method will not throw an exception if it can not find something, it only returns None

Returns

the method variation callable for the given data (or none, if the method does not exist in this object or in a parent class of it)

get_next_parent_feature() → Optional[Type[_balder.feature.Feature]]

This method returns the next parent class of this feature, which is still a subclass of Feature. If the next parent class is Feature, None will be returned.

Returns

the parent Feature class or None if no parent exists

get_original_vdevice_definitions() → Dict[str, Type[_balder.vdevice.VDevice]]

This method returns the VDevice definitions that are the original definitions for this feature.

property related_cls: Type[_balder.feature.Feature]

This method returns the related class that belongs to that controller.

save_all_current_vdevice_references_as_originals()

This method saves the current existing VDevice definitions inside this feature as originals.

set_active_method_variation(method_selection: Dict[str, Tuple[Type[_balder.vdevice.VDevice], _balder.connection.Connection, Callable]])

This method sets the active method variation selection for the related feature class. :param method_selection: the method selection that should be set

set_class_based_for_vdevice(data: Optional[Dict[Type[_balder.vdevice.VDevice], List[Union[_balder.connection.Connection, Type[_balder.connection.Connection]]]]])

This method allows to set the data of the class based @for_vdevice decorator.

set_method_based_for_vdevice(data: Optional[Dict[str, Dict[Callable, Dict[Type[_balder.vdevice.VDevice], List[_balder.connection.Connection]]]]])

This method allows to set the data for the method based @for_vdevice decorator.

validate_inherited_class_based_vdevice_cnn_subset()

This method checks that the class based for_vdevice values of a child Feature class are contained_in the related VDevice defined in a parent Feature class.

validate_inner_classes()

This method validates all inner classes of the related feature and secures that none of these subclasses are subclass of Device but not subclasses from VDevice. Of course other inner-classes that are not required for balder are allowed too.

validate_inner_vdevice_inheritance()

This method validates the inheritance of all inner VDevice classes of the feature that belongs to this controller.

It secures that new VDevice classes are added or existing VDevice classes are completely being overwritten for every feature level. The method only allows the overwriting of VDevices, which are subclasses of another VDevice that is defined in a parent Feature class. In addition, the class has to have the same name as its parent class.

The method also secures that the user overwrites instantiated Feature classes in the VDevice (class property name is the same) only with subclasses of the element that is being overwritten. New Features can be added without consequences.