Utilities

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

Components

class balderhub.textual.lib.utils.components.TextualElement(bridge: TextualElementBridge)

Bases: AbstractElement, VisibleMixin

The basic Textual Element

property bridge: TextualElementBridge

Returns:: returns the underlying bridge object

classmethod by_raw_element(driver: TextualDriverClass, raw_element: DOMNode, parent: TextualElement | TextualElementBridge = None)

This method returns the textual element by the raw textual framework element.

Parameters:

driver – the textual driver
raw_element – the raw textual engine element (f.e. DOMNode or Widget)
parent – optional a parent textual element, if the selector is relative

Returns:

the textual element that is identified by the selector

classmethod by_selector(driver: TextualDriverClass, selector: Selector, parent: TextualElement | TextualElementBridge = None)

This method returns the element for the provided selector.

Parameters:

driver – the textual driver
selector – the selector to identify the element
parent – optional a parent textual element, if the selector is relative

Returns:

the textual element that is identified by the selector

property driver: TextualDriverClass

Returns:: returns the underlying textual driver

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

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

property parent_bridge: TextualElementBridge

Returns:: returns the bridge of the parent element (if any)

property raw_element: DOMNode

Returns:: returns the raw textual engine element

Textual Widgets

class balderhub.textual.lib.utils.components.widgets.Button(bridge: TextualElementBridge)

Bases: TextualElement, ClickableMixin, RectangleMixin

A textual Button object (see: https://textual.textualize.io/widgets/button/)

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

property height: float

Returns:: returns the height of the element

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.

property width: float

Returns:: returns the width of the element

class balderhub.textual.lib.utils.components.widgets.Checkbox(bridge: TextualElementBridge)

Bases: TextualElement

A textual Checkbox object (see: https://textual.textualize.io/widgets/checkbox/)

class balderhub.textual.lib.utils.components.widgets.DataTable(bridge: TextualElementBridge)

Bases: TextualElement

A textual DataTable object (see: https://textual.textualize.io/widgets/data_table/)

class balderhub.textual.lib.utils.components.widgets.Digits(bridge: TextualElementBridge)

Bases: TextualElement, HasValueMixin

A textual Digits object (see: https://textual.textualize.io/widgets/digits/)

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

class balderhub.textual.lib.utils.components.widgets.DirectoryTree(bridge: TextualElementBridge)

Bases: TextualElement

A textual DirectoryTree object (see: https://textual.textualize.io/widgets/directory_tree/)

class balderhub.textual.lib.utils.components.widgets.Footer(bridge: TextualElementBridge)

Bases: TextualElement

A textual Footer object (see: https://textual.textualize.io/widgets/footer/)

class balderhub.textual.lib.utils.components.widgets.Header(bridge: TextualElementBridge)

Bases: TextualElement

A textual Header object (see: https://textual.textualize.io/widgets/header/)

class balderhub.textual.lib.utils.components.widgets.Input(bridge: TextualElementBridge)

Bases: TextualElement

A textual Input object (see: https://textual.textualize.io/widgets/input/)

class balderhub.textual.lib.utils.components.widgets.Label(bridge: TextualElementBridge)

Bases: TextualElement

A textual Label object (see: https://textual.textualize.io/widgets/label/)

class balderhub.textual.lib.utils.components.widgets.ListItem(bridge: TextualElementBridge)

Bases: TextualElement

A textual ListItem object (see: https://textual.textualize.io/widgets/list_item/)

class balderhub.textual.lib.utils.components.widgets.LoadingIndicator(bridge: TextualElementBridge)

Bases: TextualElement

A textual LoadingIndicator object (see: https://textual.textualize.io/widgets/loading_indicator/)

class balderhub.textual.lib.utils.components.widgets.Log(bridge: TextualElementBridge)

Bases: TextualElement

A textual Log object (see: https://textual.textualize.io/widgets/log/)

class balderhub.textual.lib.utils.components.widgets.OptionList(bridge: TextualElementBridge)

Bases: TextualElement

A textual OptionList object (see: https://textual.textualize.io/widgets/option_list/)

class balderhub.textual.lib.utils.components.widgets.Placeholder(bridge: TextualElementBridge)

Bases: TextualElement

A textual Placeholder object (see: https://textual.textualize.io/widgets/placeholder/)

class balderhub.textual.lib.utils.components.widgets.ProgressBar(bridge: TextualElementBridge)

Bases: TextualElement

A textual ProgressBar object (see: https://textual.textualize.io/widgets/progress_bar/)

class balderhub.textual.lib.utils.components.widgets.RadioButton(bridge: TextualElementBridge)

Bases: TextualElement

A textual RadioButton object (see: https://textual.textualize.io/widgets/radiobutton/)

class balderhub.textual.lib.utils.components.widgets.Rule(bridge: TextualElementBridge)

Bases: TextualElement

A textual Rule object (see: https://textual.textualize.io/widgets/rule/)

class balderhub.textual.lib.utils.components.widgets.Select(bridge: TextualElementBridge)

Bases: TextualElement

A textual Select object (see: https://textual.textualize.io/widgets/select/)

class balderhub.textual.lib.utils.components.widgets.Static(bridge: TextualElementBridge)

Bases: TextualElement

A textual Static object (see: https://textual.textualize.io/widgets/static/)

class balderhub.textual.lib.utils.components.widgets.Switch(bridge: TextualElementBridge)

Bases: TextualElement

A textual Switch object (see: https://textual.textualize.io/widgets/switch/)

class balderhub.textual.lib.utils.components.widgets.Tabs(bridge: TextualElementBridge)

Bases: TextualElement

A textual Tabs object (see: https://textual.textualize.io/widgets/tabs/)

class balderhub.textual.lib.utils.components.widgets.TextArea(bridge: TextualElementBridge)

Bases: TextualElement

A textual TextArea object (see: https://textual.textualize.io/widgets/text_area/)

class balderhub.textual.lib.utils.components.widgets.Tree(bridge: TextualElementBridge)

Bases: TextualElement

A textual Tree object (see: https://textual.textualize.io/widgets/tree/)

Textual Container Objects

class balderhub.textual.lib.utils.components.widgets.containers.Collapsible(bridge: TextualElementBridge)

Bases: TextualElement

A textual Collapsible object (see: https://textual.textualize.io/widgets/collapsible/)

class balderhub.textual.lib.utils.components.widgets.containers.ContentSwitcher(bridge: TextualElementBridge)

Bases: TextualElement

A textual ContentSwitcher object (see: https://textual.textualize.io/widgets/content_switcher/)

class balderhub.textual.lib.utils.components.widgets.containers.ListView(bridge: TextualElementBridge)

Bases: TextualElement

A textual ListView object (see: https://textual.textualize.io/widgets/list_view/)

class balderhub.textual.lib.utils.components.widgets.containers.RadioSet(bridge: TextualElementBridge)

Bases: TextualElement

A textual RadioSet object (see: https://textual.textualize.io/widgets/radioset/)

class balderhub.textual.lib.utils.components.widgets.containers.SelectionList(bridge: TextualElementBridge)

Bases: TextualElement

A textual SelectionList object (see: https://textual.textualize.io/widgets/selection_list/)

class balderhub.textual.lib.utils.components.widgets.containers.TabbedContent(bridge: TextualElementBridge)

Bases: TextualElement

A textual TabbedContent object (see: https://textual.textualize.io/widgets/tabbed_content/)

Drivers

class balderhub.textual.lib.utils.drivers.TextualDriverClass(app_instance: App)

Bases: BaseDriverClass

main textual driver class

click(widget: Widget): Executes a mouse click on the given widget

find_bridge(selector: Selector) → TextualFullyReidentifiableElementBridge

This method returns a specific bridge object identified by the provided selector.

Parameters:: selector – the selector to identify the element
Returns:: the bridge object

find_bridges(selector: Selector) → list[balderhub.textual.lib.utils.element_bridges.textual_not_reidentifiable_element_bridge.TextualNotReidentifiableElementBridge]

This method returns a list of bridge objects identified by the provided selector.

Parameters:: selector – the selector to identify the elements
Returns:: a list of bridge objects

find_raw_element(selector: Selector) → DOMNode

This method returns the raw textual element that matches the given selector.

Parameters:: selector – the selector to match

find_raw_elements(selector: Selector) → list[textual.dom.DOMNode]

This method returns all matching raw textual elements that match the given selector.

Parameters:: selector – the selector to match

get_bridge_for_raw_element(raw_element: DOMNode, parent: TextualElementBridge | None = None) → TextualNotReidentifiableElementBridge

This method returns the bridge object for a raw textual element.

Parameters:

raw_element – the raw textual element
parent – the parent bridge of the element that is a parent of this element (or None if there is no parent specified)

Returns:

the newly created bridge object

press(*keys: str)

This method executes key presses within the application.

Parameters:: keys – the keys to press

quit(): This method releases all resources belonging to this driver.

Element Bridges

class balderhub.textual.lib.utils.element_bridges.TextualElementBridge(driver: TextualDriverClass, parent: TextualElementBridge | None)

Bases: BaseElementBridge, ABC

basic web-element-bridge implementation for Textual Elements

clear(): Clears the element

click() → None

This method clicks the element.

The Element Click command scrolls into view the element if it is not already pointer-interactable, and clicks its in-view center point.

If the element’s center point is obscured by another element, an element click intercepted error is returned. If the element is outside the viewport, an element not interactable error is returned.

property driver: TextualDriverClass

Returns:: returns the driver class, this bridge was created from

exists() → bool

This method returns True if the element exists. An element exists if it is still part of the DOM.

Note

This does not mean, that it needs to be visible! Use the BaseWebElementBridge.is_visible() method instead.`

Returns:: returns True if the element does exist otherwise false.

abstract find_bridge(selector: Selector) → TextualFullyReidentifiableElementBridge | TextualPartlyReidentifiableElementBridge

Method to directly returning the bridge of a specific raw web element by its selector that is a child of the current one. In case that the element can be reidentified completely by the selector (f.e. because the selector is By.ID) the method returns a FullyReidentifiableElementBridge object. Otherwise, the method returns a PartlyReidentifiableElementBridge object.

Parameters:: selector – the selector specifying the element (relative to this one)
Returns:: the bridge object of the element specified by the selector

find_bridges(selector: Selector) → List[TextualNotReidentifiableElementBridge]

Method to directly returning a list of bridge objects for raw web elements matching the provided relative selector as a child of the current one

Parameters:: selector – the selector specifying the elements (relative to this one)
Returns:: a list with all matching bridge objects (depending on the underlying framework)

find_raw_element(selector: Selector) → DOMNodeTypeT

Method to find a specific raw web element by its selector that is a child of the current one

Parameters:: selector – the selector specifying the element (relative to this one)
Returns:: the raw web element (depending on the underlying framework)

find_raw_elements(selector: Selector) → List[DOMNodeTypeT]

Method to find raw web elements matching the provided relative selector as a child of the current one

Parameters:: selector – the selector specifying the elements (relative to this one)
Returns:: the raw web element (depending on the underlying framework)

get_rect() → tuple[int, int, int, int]

Returns:: the rect of the element (x, y, width, height)

get_text_content() → str

This method returns the text of the element as a string.

Returns:: returns the text of the element as a string

is_clickable() → bool

This method returns True if the element is (theoretically) clickable.

Returns:: returns True if the element is (theoretically) clickable, otherwise False.

is_disabled() → bool

This method returns True if the element is visible.

Returns:: returns True if the element does exist otherwise false.

is_selected() → bool

The Is Element Selected command determines if the referenced element is selected or not. This operation only makes sense on input elements of the Checkbox- and Radio Button states, or on option elements.

Returns:: returns True if the element is selected.

is_visible() → bool

This method returns True if the element is visible.

Returns:: returns True if the element is visible otherwise false.

property parent: TextualElementBridge | None

Returns:: returns the defined parent web element bridge if a parent does exist

property raw_element: DOMNodeTypeT

Returns:: returns the raw web element (depending on the underlying framework)

scroll_for(scroll_steps: int)

This method scrolls for one row / column.

Parameters:: scroll_steps – the number of steps to scroll (positive: scrolls forward, negative: scrolls backward)

scroll_to_beginning(): This method scrolls to the beginning of the scrollable element. It needs to make sure, that after calling it, the scrollable element is always at the beginning of its content. It raises an error, in case the element can not be scrolled.

scroll_to_end(): This method scrolls to the end of the scrollable element. It needs to make sure, that after calling it, the scrollable element is always at the end of its content. It raises an error, in case the element can not be scrolled.

select_by_option_index(index: int) → None: This method selects the element by index. :param index: the option index that should be selected

select_by_option_value(value: str): This method selects the element by value. :param value: the option value that should be selected

select_by_text(text_of_option_to_select: str) → None: This method selects the element by shown text. :param text_of_option_to_select: the expected text in the option that should be selected

send_keys(text: str) → None

This method inserts a text into the field.

The Element Send Keys command scrolls into view the form control element and then sends the provided keys to the element. In case the element is not keyboard-interactable, an element not interactable error is returned.

Parameters:: text – the text that should be inserted into the field

class balderhub.textual.lib.utils.element_bridges.TextualFullyReidentifiableElementBridge(driver: TextualDriverClass, selector: Selector, parent: TextualFullyReidentifiableElementBridge | None = None)

Bases: TextualElementBridge

A fully reidentifiable element bridge specifies the element in an absolute manner. It doesn’t matter if the element has a full absolute selector or has parents with re-identifiable selectors (so all parents need to be FullyReidentifiableElementBridge objects)

exists() → bool

This method returns True if the element exists. An element exists if it is still part of the DOM.

Note

This does not mean, that it needs to be visible! Use the BaseWebElementBridge.is_visible() method instead.`

Returns:: returns True if the element does exist otherwise false.

find_bridge(selector: Selector) → TextualFullyReidentifiableElementBridge

Method to directly returning the bridge of a specific raw web element by its selector that is a child of the current one. In case that the element can be reidentified completely by the selector (f.e. because the selector is By.ID) the method returns a FullyReidentifiableElementBridge object. Otherwise, the method returns a PartlyReidentifiableElementBridge object.

Parameters:: selector – the selector specifying the element (relative to this one)
Returns:: the bridge object of the element specified by the selector

property parent: TextualFullyReidentifiableElementBridge | None

Returns:: returns the defined parent web element bridge if a parent does exist

property raw_element: TextualElement

Returns:: returns the raw web element (depending on the underlying framework)

re_identify_raw_element() → DOMNode

This method re-identifies the element by requesting it again from the main driver. This method automatically updates the internal reference for this object.

Returns:: the re-identified raw element

property selector: Selector

Returns:: the absolute selector this element bridge has.

class balderhub.textual.lib.utils.element_bridges.TextualNotReidentifiableElementBridge(driver: TextualDriverClass, raw_element: DOMNode, parent: TextualElementBridge | None = None)

Bases: TextualElementBridge

A non reidentifiable element bridge can not re-identify an element by itself, because it does not specify absolute selectors.

exists()

This method returns True if the element exists. An element exists if it is still part of the DOM.

Note

This does not mean, that it needs to be visible! Use the BaseWebElementBridge.is_visible() method instead.`

Returns:: returns True if the element does exist otherwise false.

find_bridge(selector: Selector) → TextualPartlyReidentifiableElementBridge

Method to directly returning the bridge of a specific raw web element by its selector that is a child of the current one. In case that the element can be reidentified completely by the selector (f.e. because the selector is By.ID) the method returns a FullyReidentifiableElementBridge object. Otherwise, the method returns a PartlyReidentifiableElementBridge object.

Parameters:: selector – the selector specifying the element (relative to this one)
Returns:: the bridge object of the element specified by the selector

property parent: TextualElementBridge | None

Returns:: returns the defined parent web element bridge if a parent does exist

class balderhub.textual.lib.utils.element_bridges.TextualPartlyReidentifiableElementBridge(driver: TextualDriverClass, relative_selector: Selector, parent: TextualPartlyReidentifiableElementBridge | TextualNotReidentifiableElementBridge)

Bases: TextualElementBridge

A partly reidentifiable element bridge specifies a bridge that does only have a relative selector to another bridge object that is not re-identifiable. This type of bridges are only reidentifiable if their parent element is in a reliable state.

exists() → bool

This method returns True if the element exists. An element exists if it is still part of the DOM.

Note

This does not mean, that it needs to be visible! Use the BaseWebElementBridge.is_visible() method instead.`

Returns:: returns True if the element does exist otherwise false.

find_bridge(selector: Selector) → TextualPartlyReidentifiableElementBridge

Method to directly returning the bridge of a specific raw web element by its selector that is a child of the current one. In case that the element can be reidentified completely by the selector (f.e. because the selector is By.ID) the method returns a FullyReidentifiableElementBridge object. Otherwise, the method returns a PartlyReidentifiableElementBridge object.

Parameters:: selector – the selector specifying the element (relative to this one)
Returns:: the bridge object of the element specified by the selector

property parent: TextualPartlyReidentifiableElementBridge | TextualNotReidentifiableElementBridge | None

Returns:: returns the defined parent web element bridge if a parent does exist

property raw_element: TextualElement

Returns:: returns the raw web element (depending on the underlying framework)

re_identify_raw_element() → TextualElement

This method re-identifies the element by requesting it again from the main driver. This method automatically updates the internal reference for this object.

Returns:: the re-identified raw element

property relative_selector: Selector

Returns:: returns the relative selector.