API Reference

This section provides detailed documentation for all public modules, classes, and functions in unbrowsed.

Matchers Module

unbrowsed matchers.

class unbrowsed.matchers.TextMatch(text: str, exact=True)[source]

Bases: object

Wrapper class for text matching.

matches(other: str) → bool[source]

Queries Module

unbrowsed queries.

class unbrowsed.queries.Result(element: LexborNode)[source]

Bases: object

Wrapper class for query result.

to_have_attribute(name: str, value: Any = None) → bool[source]
Check if the element has the specified attribute

(and optionally matches value).

to_have_text_content(text: str, exact: bool = True) → bool[source]

Check if the element’s text content matches the specified text.

Parameters:

  • text – The text content to check for.

  • exact – Defaults to True; matches full strings, case-sensitive. When False, matches substrings and is not case-sensitive.

Returns:

True if the element’s text content matches the specified text, False otherwise.

Added in version 0.1.0a11.

unbrowsed.queries.get_all_by_role(dom: LexborHTMLParser, role: Literal['alert', 'article', 'banner', 'button', 'generic', 'cell', 'checkbox', 'columnheader', 'combobox', 'complementary', 'contentinfo', 'definition', 'dialog', 'figure', 'form', 'grid', 'gridcell', 'group', 'heading', 'document', 'img', 'image', 'link', 'list', 'listbox', 'listitem', 'main', 'menu', 'meter', 'navigation', 'option', 'paragraph', 'presentation', 'progressbar', 'radio', 'region', 'row', 'rowgroup', 'searchbox', 'separator', 'status', 'table', 'term', 'textbox', 'time', 'treegrid'], current: bool | str | None = None) → list[Result][source]

Retrieves all elements from the DOM by their ARIA role.

Similar to query_all_by_role but throws an error if no elements are found.

Parameters:

  • dom – The parsed DOM to search within.

  • role – The ARIA role to search for.

  • current – Optional value to check for aria-current attribute. Can be a boolean or string “true”.

Returns:

A list of Result objects containing the matched elements.

Raises:

NoElementsFoundError – If no elements with the specified role are found.

Added in version 0.1.0a13.

unbrowsed.queries.get_by_label_text(dom: LexborHTMLParser, text: str, exact=True) → Result[source]

Retrieves an element from the DOM by its label text.

Similar to query_by_label_text but throws an error if no element is found or if multiple elements are found with the matching label text.

Parameters:

  • dom – The parsed DOM to search within.

  • text – The label text to search for.

  • exact – Defaults to True; matches full strings, case-sensitive. When False, matches substrings and is not case-sensitive.

Returns:

A Result containing the matched element.

Raises:

Added in version 0.1.0a9: The exact parameter.

unbrowsed.queries.get_by_role(dom: LexborHTMLParser, role: Literal['alert', 'article', 'banner', 'button', 'generic', 'cell', 'checkbox', 'columnheader', 'combobox', 'complementary', 'contentinfo', 'definition', 'dialog', 'figure', 'form', 'grid', 'gridcell', 'group', 'heading', 'document', 'img', 'image', 'link', 'list', 'listbox', 'listitem', 'main', 'menu', 'meter', 'navigation', 'option', 'paragraph', 'presentation', 'progressbar', 'radio', 'region', 'row', 'rowgroup', 'searchbox', 'separator', 'status', 'table', 'term', 'textbox', 'time', 'treegrid'], current: bool | str | None = None, name: str | None = None, description: str | None = None) → Result[source]

Retrieves an element from the DOM by its ARIA role.

Similar to query_by_role but throws an error if no element is found or if multiple elements are found with the matching role.

Parameters:

  • dom – The parsed DOM to search within.

  • role – The ARIA role to search for.

  • current – The value to check for aria-current attribute. Can be a boolean or string “true”.

  • name – The accessible name of the element.

  • description – The accessible description of the element.

Returns:

A Result containing the matched element and context description.

Raises:

Added in version 0.1.0a10.

Added in version 0.1.0a15: The name parameter.

Added in version 0.1.0a16: The description parameter.

unbrowsed.queries.get_by_text(dom: LexborHTMLParser, text: str, exact=True) → Result[source]

Retrieves an element from the DOM by its text content.

Similar to query_by_text but throws an error if no element is found or if multiple elements are found with the matching text content.

Parameters:

  • dom – The parsed DOM to search within.

  • text – The text content to search for.

  • exact – Defaults to True; matches full strings, case-sensitive. When False, matches substrings and is not case-sensitive.

Returns:

A Result containing the matched element.

Raises:

Added in version 0.1.0a9: The exact parameter.

unbrowsed.queries.query_all_by_role(dom: LexborHTMLParser, role: Literal['alert', 'article', 'banner', 'button', 'generic', 'cell', 'checkbox', 'columnheader', 'combobox', 'complementary', 'contentinfo', 'definition', 'dialog', 'figure', 'form', 'grid', 'gridcell', 'group', 'heading', 'document', 'img', 'image', 'link', 'list', 'listbox', 'listitem', 'main', 'menu', 'meter', 'navigation', 'option', 'paragraph', 'presentation', 'progressbar', 'radio', 'region', 'row', 'rowgroup', 'searchbox', 'separator', 'status', 'table', 'term', 'textbox', 'time', 'treegrid'], current: bool | str | None = None) → list[Result][source]

Queries the DOM for all elements with the specified ARIA role.

Parameters:

  • dom – The parsed DOM to search within.

  • role – The ARIA role to search for.

  • current – The value to check for aria-current attribute. Can be a boolean or string “true”.

Returns:

A list of Result objects containing the matched elements.

Added in version 0.1.0a13.

unbrowsed.queries.query_by_label_text(dom: LexborHTMLParser, text: str, exact=True) → Result | None[source]

Queries the DOM for an element associated with a label containing the specified text.

Parameters:

  • dom – The parsed DOM to search within.

  • text – The label text to search for.

  • exact – Defaults to True; matches full strings, case-sensitive. When False, matches substrings and is not case-sensitive.

Returns:

A Result containing the matched element.

Raises:

Added in version 0.1.0a9: The exact parameter.

unbrowsed.queries.query_by_role(dom: LexborHTMLParser, role: Literal['alert', 'article', 'banner', 'button', 'generic', 'cell', 'checkbox', 'columnheader', 'combobox', 'complementary', 'contentinfo', 'definition', 'dialog', 'figure', 'form', 'grid', 'gridcell', 'group', 'heading', 'document', 'img', 'image', 'link', 'list', 'listbox', 'listitem', 'main', 'menu', 'meter', 'navigation', 'option', 'paragraph', 'presentation', 'progressbar', 'radio', 'region', 'row', 'rowgroup', 'searchbox', 'separator', 'status', 'table', 'term', 'textbox', 'time', 'treegrid'], current: bool | str | None = None, name: str | None = None, description: str | None = None) → Result | None[source]

Queries the DOM for an element with the specified ARIA role.

Parameters:

  • dom – The parsed DOM to search within.

  • role – The ARIA role to search for.

  • current – The value to check for aria-current attribute. Can be a boolean or string “true”.

  • name – The accessible name of the element.

  • description – The accessible description of the element.

Returns:

A Result containing the matched element.

Raises:

MultipleElementsFoundError – If multiple elements with matching role are found.

Added in version 0.1.0a10.

Added in version 0.1.0a15: The name parameter.

Added in version 0.1.0a16: The description parameter.

unbrowsed.queries.query_by_text(dom: LexborHTMLParser, text: str, exact=True) → Result | None[source]

Queries the DOM for an element containing the specified text.

Parameters:

  • dom – The parsed DOM to search within.

  • text – The text content to search for.

  • exact – Defaults to True; matches full strings, case-sensitive. When False, matches substrings and is not case-sensitive.

Returns:

A Result containing the matched element.

Raises:

MultipleElementsFoundError – If multiple elements with matching text are found.

Added in version 0.1.0a9: The exact parameter.

Exceptions Module

unbrowsed exceptions.

exception unbrowsed.exceptions.MultipleElementsFoundError(message)[source]

Bases: Exception

exception unbrowsed.exceptions.NoElementsFoundError(message)[source]

Bases: Exception