Utilities

This section shows general objects and helper functions that are used with this package.

Components

class balderhub.gui.lib.utils.components.AbstractElement

Bases: ABC

The base class for any kind of elements mostly used in another element or a PageFeature

abstract exists() → bool

Callback that checks if this element exists.

Note

The existence of an element does not necessarily mean that it visible.

Returns:: True if it does exist, otherwise False

exists_within(time_sec: float) → bool

This method waits for a maximum of time_sec seconds for the existence of this element. If the element does not exist within the provided time time_sec, the method returns False.

Parameters:: time_sec – the maximum time to wait for this element to exist
Returns:: True if it does exist, otherwise False

wait_to_be_removed_for(timeout_sec: float) → AbstractElementTypeT

This method waits for a maximum of timeout_sec seconds for the removement of this element.

Parameters:: timeout_sec – the maximum time to wait for this element to be removed
Raises:: TimeoutError – if timeout is exceeded

wait_to_exist_for(timeout_sec: float) → AbstractElementTypeT

This method waits for a maximum of timeout_sec seconds for the existence of this element.

Parameters:: timeout_sec – the maximum time in seconds to wait for this element to exist
Raises:: TimeoutError – if timeout is exceeded

was_removed_within(time_sec: float) → bool

This method waits for a maximum of time_sec seconds for the removement of this element. If the element still exists after time_sec, the method returns False.

Parameters:: time_sec – the maximum time to wait for this element to be removed
Returns:: True if it does not exist anymore (within the time_sec), otherwise False

Mixins

Mixins are used to standardize functionality of graphical user interfaces.

class balderhub.gui.lib.utils.mixins.CircleMixin

Bases: ABC

mixin class that describes a circle object

abstract property diameter: float

Returns:: returns the circle diameter

class balderhub.gui.lib.utils.mixins.ClickableMixin

Bases: ABC

mixin class that describes a clickable element

abstract click() → None: Executes a click at the element

abstract is_clickable() → bool

This method checks if the element is theoretically clickable. This means, that no other element does cover it up.

Returns:: True if the element should be theoretically clickable, False otherwise.

is_clickable_within(time_sec: float) → bool

This method waits for a maximum of time_sec seconds for the element to be clickable. If the element is not clickable within the provided time time_sec, the method returns False.

Parameters:: time_sec – the maximum time to wait for this element to be clickable
Returns:: True if it is clickable, otherwise False

wait_to_be_clickable_for(timeout_sec: float) → ClickableMixinTypeT

This method waits for a maximum of timeout_sec seconds for the element to be clickable.

Parameters:: timeout_sec – the maximum time in seconds to wait for this element to be clickable
Raises:: TimeoutError – if timeout is exceeded

class balderhub.gui.lib.utils.mixins.HasValueMixin

Bases: ABC

mixin class that describes an element that can have a value

abstract get_value() → object: This method returns the value of the element. :return: the value of the element

class balderhub.gui.lib.utils.mixins.ListContainerMixin

Bases: ABC

mixin class that describes that the element is a list-container

abstract get_child_elements() → List[AbstractElement]: This method returns a list of elements that are contained within this container. :return: the list of elements that are contained within this container.

class balderhub.gui.lib.utils.mixins.PaginatedContainerMixin

Bases: ListContainerMixin, ABC

This mixin is used for list container with a pagination functionality

exception PageDoesNotExist

Bases: Exception

This exception is raised when a page does not exist.

abstract property current_page: int

Returns:: returns the current page number

abstract go_to_next_page(): This method goes to the next page :raises PageDoesNotExist: if the current page is the latest already

abstract go_to_page(page: int) → None: This method goes to the provided page. :param page: the page index to go :raises PageDoesNotExist: if the page provided page does not exist

abstract go_to_previous_page(): This method goes to the previous page :raises PageDoesNotExist: if the current page is the latest already

abstract property min_max_page: tuple[int, int]

Returns:: returns the min and the max page that exists for this paginated list

class balderhub.gui.lib.utils.mixins.RectangleMixin

Bases: ABC

mixin class that describes a rectangle object

abstract property height: float

Returns:: returns the height of the element

abstract property width: float

Returns:: returns the width of the element

class balderhub.gui.lib.utils.mixins.ScrollableMixin

Bases: ABC

mixin class that describes that the content of this element can be scrolled

abstract scroll_once_backward() → None: This method scrolls for one element backward

abstract scroll_once_forward() → None: This method scrolls for one element forward

abstract scroll_to_beginning() → None: This method scrolls to the beginning of the scrollable area

abstract scroll_to_end() → None: This method scrolls to the end of the scrollable area

class balderhub.gui.lib.utils.mixins.SelectByHiddenValueMixin

Bases: ABC

mixin class that describes that this element has selectable elements that can be selected-by-value

abstract select_by_value(value: object) → None: This method selects the element by its value :param value: the value to select

class balderhub.gui.lib.utils.mixins.SelectByIndexMixin

Bases: ABC

mixin class that describes that this element has selectable elements that can be selected-by-index

abstract select_by_index(index: int) → None: This method selects the element by its index :param index: the index to select

class balderhub.gui.lib.utils.mixins.SelectByVisibleTextMixin

Bases: ABC

mixin class that describes that this element has selectable elements that can be selected-by-visible-text

abstract select_by_text(visible_text: str): This method selects the element by visible text :param visible_text: the visible text of the element that should be selected

class balderhub.gui.lib.utils.mixins.TwoStateCheckboxMixin

Bases: ABC

mixin class that describes that this element is a two-state checkbox

abstract is_checked() → bool: This method returns True if the element is checked, otherwise False :return: True if the element is checked, otherwise False

class balderhub.gui.lib.utils.mixins.TypeableMixin

Bases: ABC

mixin class that describes that you can type text in this checkbox

abstract type_text(text: str, clean_before: bool = False) → None

This method types a text in this element.

Parameters:

text – the text that should be inserted
clean_before – True if the system should make sure that all previous filled text is deleted before inserting any new text

class balderhub.gui.lib.utils.mixins.VisibleMixin

Bases: ABC

mixin class that describes a visible element

abstract is_visible() → bool

This method returns True if the element is visible.

Note

This method also returns True if the element is theoretically visible but not visible because other elements cover it up.

Returns:: True if the element is shown, otherwise it returns False

is_visible_within(time_sec: float) → bool

This method waits for a maximum of time_sec seconds for the element to be visible. If the element is not shown within the provided time time_sec, the method returns False.

Parameters:: time_sec – the maximum time to wait for this element to be visbile
Returns:: True if it is visible, otherwise False

wait_to_be_hidden_for(timeout_sec: float) → VisibleMixinTypeT

This method waits for a maximum of timeout_sec seconds for the element to be hidden.

Parameters:: timeout_sec – the maximum time to wait for this element to be hidden
Raises:: TimeoutError – if timeout is exceeded

wait_to_be_visible_for(timeout_sec: float) → VisibleMixinTypeT

This method waits for a maximum of timeout_sec seconds for the element to be visible.

Parameters:: timeout_sec – the maximum time in seconds to wait for this element to be visible
Raises:: TimeoutError – if timeout is exceeded

was_hidden_within(time_sec: float) → bool

This method waits for a maximum of time_sec seconds for the hiddenness of this element. If the element is still visible after time_sec, the method returns False.

Parameters:: time_sec – the maximum time to wait for this element to be hidden
Returns:: True if it is not shown anymore (within the time_sec), otherwise False

Selector

class balderhub.gui.lib.utils.BaseSelector(by_type: By, identifier: str)

Bases: ABC

Base class that is used to identify GUI elements. It is normally overwritten in sub packages.

class By(value)

Bases: Enum

Enum that describes the selecting type

exception NoTranslationPossibleError

Bases: Exception

raised when no translation is possible, because no translation was defined.

property by_type: By

Returns:: the used selecting type

property identifier: str

Returns:: the value of the selector, that is used to identify the element

translate_to(other_selector_type: type[ConvertedBaseSelectorTypeT]) → ConvertedBaseSelectorTypeT

This method translates the given selector value to the corresponding selector value of the provided selector type.

Parameters:: other_selector_type – the selector type object this selector should translate to
Returns:: the same selector value like this selector but as translated object from type given in other_selector_type