implementation.selenium

Module with selenium implementations compatible with soupsavvy interfaces. - SeleniumElement class is an adapter making selenium tree, compatible with IElement interface and usable across the library. - SeleniumBrowser class is an adapter making selenium WebDriver compatible with IBrowser.

class SeleniumElement(node: N, *args, **kwargs)[source]

Bases: IElement[WebElement]

Implementation of IElement for selenium tree. Adapter for selenium objects, that makes them usable across the library.

Example

>>> from soupsavvy.implementation.selenium import SeleniumElement
... from selenium.ISeleniumDriver.common.by import By
... node = driver.find_element(By.TAG_NAME, "div")
... element = SeleniumElement(node)

find_all(name: str | None = None, attrs: dict[str, str | Pattern[str]] | None = None, recursive: bool = True, limit: int | None = None) → list[Self][source]

Finds all elements that match specified element name and attributes.

Parameters

namestr, optional: Name of the element to search for. If None, matches all elements.
attrsdict[str, str | Pattern[str]], optional: Dictionary of attributes to match. Supports exact matches and regex patterns.
recursivebool, optional: If True, searches recursively through all descendants. If False, searches only direct children.
limitint, optional: Maximum number of elements to return. If None, returns all matching elements.

Returns

list[Self]: List of elements that match the criteria, in depth-first order.

find_subsequent_siblings(limit: int | None = None) → list[Self][source]

Finds siblings that follow this node in the document structure.

Parameters

limitint, optional: Maximum number of sibling nodes to return. If None, returns all siblings.

Returns

list[Self]: List of subsequent sibling elements, in document order.

find_ancestors(limit: int | None = None) → list[Self][source]

Finds all ancestor nodes up to the root of the document.

Parameters

limitint, optional: Maximum number of ancestors to return, starting from the closest ancestor. If None, returns all ancestors.

Returns

list[Self]: List of ancestor nodes, from nearest to root.

property children: Iterable[Self]

Returns an iterable of the direct child elements of this node.

Notes

Only tag elements are included; text and comment nodes are excluded.

Returns

Iterable[Self]: Iterable of direct child nodes, in document order.

property descendants: Iterable[Self]

Returns an iterable of all descendant nodes of this node.

Notes

Only tag elements are included; text and comment nodes are excluded. Nodes are returned in depth-first order.

Returns

Iterable[Self]: Iterable of all descendant nodes.

property parent: Self | None

Returns the immediate parent node of this element, if it exists.

Returns

Optional[Self]: The parent element, or None if this is the root node.

get_attribute(name: str) → str | None[source]

Retrieves the value of a specified attribute for this node.

Parameters

namestr: Name of the attribute.

Returns

Optional[str]: The attribute value as a string, or None if the attribute does not exist.

Notes

For dynamic attributes (e.g., in browser contexts), the returned value reflects the current state of the element.

property name: str: Returns the tag name of this element.

property text: str

Gets the combined text content of this element.

Notes

Concatenates all text nodes within this element. The format may vary slightly across implementations depending on handling of whitespace or nested elements.

Returns

str: Text content of this element, or an empty string if none is found.

css(selector: str) → SeleniumCSSApi[source]

Returns a SelectionApi for CSS-based selection.

Parameters

selectorAny: The CSS selector to apply.

Returns

SelectionApi: Initialized SelectionApi instance for CSS selection.

xpath(selector: str) → SeleniumXPathApi[source]

Returns a SelectionApi for XPath-based selection.

Parameters

selectorAny: The XPath selector to apply.

Returns

SelectionApi: Initialized SelectionApi instance for XPath selection.

class SeleniumBrowser(browser: B, *args, **kwargs)[source]

Bases: IBrowser[WebDriver, SeleniumElement]

Implementation of IBrowser for selenium WebDriver. Adapter for selenium WebDriver, that makes them usable across the library.

Example

>>> from soupsavvy.implementation.selenium import SeleniumBrowser
... from selenium import webdriver
... driver = webdriver.Chrome()
... browser = SeleniumBrowser(driver)

navigate(url: str) → None[source]

Navigates the browser to the specified URL.

Parameters

urlstr: The URL to navigate to.

click(element: SeleniumElement) → None[source]

Performs a click action on the specified element.

Parameters

elementIElement: The target element of implementation compatible with browser that will be clicked.

send_keys(element: SeleniumElement, value: str, clear: bool = True) → None[source]

Sends keystrokes to the specified element.

Parameters

elementIElement: The target element of implementation compatible with browser to interact with.
valuestr: The value to insert into the element.
clearbool, optional: If True, clears existing content before sending keys. Defaults to True.

get_document() → SeleniumElement[source]

Returns the html document of the current page as an IElement.

Returns

IElement: The html document of the current page, soupsavvy implementation compatible with the browser.

Raises

TagNotFoundException: If the <html> element is not found on the page.

close() → None[source]: Closes the browser and releases resources.

get_current_url() → str[source]: Returns the current URL of the browser.