operations.browser

Module defining browser operations for web automation tasks. Contains typical browser operations and actions on web elements.

class ApplyTo(selector: SoupSelector, action: ElementAction)

Bases: BrowserOperation

Applies a given action to a single element selected from the browser document.

This operation uses a SoupSelector to find a target element within the browser’s DOM and then executes the provided ElementAction on it.

Parameters

selectorSoupSelector

Selector used to locate the target element in the document.

actionElementAction

Action to execute on the selected element.

Raises

soupsavvy.exceptions.FailedOperationExecution

If the element cannot be found using the provided selector.

__init__(selector: SoupSelector, action: ElementAction) → None

class Navigate(url: str)

Bases: BrowserOperation

Operation for navigating the browser to a specified URL.

Example

>>> from soupsavvy.operations.browser import Navigate
... from soupsavvy.implementation.selenium import SeleniumBrowser
... from selenium import webdriver
...
... browser = SeleniumBrowser(webdriver.Chrome())
... operation = Navigate("https://example.com")
... operation.execute(browser)

__init__(url: str) → None

Initializes the Navigate operation with the specified URL.

Parameters

urlstr

The target URL to navigate to.

class WaitImplicitly(seconds: float)

Bases: BaseOperation

Pauses execution for a specified number of seconds. Useful for browser operations that require waiting for a page to load or for dynamic content to render.

Example

>>> from soupsavvy.operations.browser import WaitImplicitly
... operation = WaitImplicitly(5)
... operation.execute(None)

It proves more useful when chained with other browser operations.

Example

>>> from soupsavvy.operations.browser import WaitImplicitly, Navigate
... from soupsavvy.implementation.selenium import SeleniumBrowser
... from selenium import webdriver
...
... browser = SeleniumBrowser(webdriver.Chrome())
... operation = Navigate("https://example.com") | WaitImplicitly(5)
... operation.execute(browser)

WaitImplicitly uses time.sleep under the hood, it does not require a browser instance to operate and can be used independently.

__init__(seconds: float) → None

Initializes the WaitImplicitly operation with the specified wait time.

Parameters

secondsfloat

Number of seconds to wait.

class Click

Bases: ElementAction

Clicks on a target element using the browser context.

Example

>>> from soupsavvy.operations.browser import Click
... from soupsavvy import TypeSelector
...
... operation = Click()
... selector = TypeSelector('button')
... element = selector.find(page, strict=True)
... operation.execute(browser)

It proves more useful when used in conjunction with ApplyTo operation, which can be integrated into browser workflows.

Example

>>> from soupsavvy.operations.browser import ApplyTo, Click, Navigate
... from soupsavvy import TypeSelector
... from soupsavvy.implementation.selenium import SeleniumBrowser
... from selenium import webdriver
...
... browser = SeleniumBrowser(webdriver.Chrome())
... action = Click()
... selector = TypeSelector('a')
... operation = Navigate("https://example.com") | ApplyTo(selector, action)
... operation.execute(browser)

class SendKeys(value: str, clear: bool = True)

Bases: ElementAction

Sends a string of keys or text input to a target element.

Example

>>> from soupsavvy.operations.browser import SendKeys
... from soupsavvy import TypeSelector
...
... operation = SendKeys("Hello, World!")
... selector = TypeSelector('input')
... element = selector.find(page, strict=True)
... operation.execute(browser)

It proves more useful when used in conjunction with ApplyTo operation, which can be integrated into browser workflows.

Example

>>> from soupsavvy.operations.browser import ApplyTo, SendKeys, Navigate
... from soupsavvy import TypeSelector
... from soupsavvy.implementation.selenium import SeleniumBrowser
... from selenium import webdriver
...
... browser = SeleniumBrowser(webdriver.Chrome())
... action = SendKeys("Hello, World!")
... selector = TypeSelector('input')
... operation = Navigate("https://example.com") | ApplyTo(selector, action)
... operation.execute(browser)

__init__(value: str, clear: bool = True) → None

Initializes the SendKeys action with the specified input value.

Parameters

valuestr

The string or keys to send to the element.

clearbool, optional

Whether to clear the element’s existing content before sending keys. Default is True.

class Find(selector: TagSearcher, strict: bool = False)

Bases: _FindBase

Finds and returns an element from the browser document using a specified selector.

Example

>>> from soupsavvy.operations.browser import Find
... from soupsavvy import TypeSelector
... from soupsavvy.implementation.selenium import SeleniumBrowser
... from selenium import webdriver
...
... browser = SeleniumBrowser(webdriver.Chrome())
... selector = TypeSelector('div')
... operation = Find(selector)
... operation.execute(browser)

It can be used as an element of browser workflows to extract information from web pages, for example: navigate -> click -> wait -> find.

__init__(selector: TagSearcher, strict: bool = False) → None

Initializes the Find operation with the specified selector.

Parameters

selectorTagSearcher

Selector used to locate the target element in the document.

strictbool, optional

Whether to enforce strict finding (raise exception if not found). Default is False.

class FindAll(selector: TagSearcher, limit: int | None = None)

Bases: _FindBase

Finds and returns elements from the browser document using a specified selector.

Example

>>> from soupsavvy.operations.browser import FindAll
... from soupsavvy import TypeSelector
... from soupsavvy.implementation.selenium import SeleniumBrowser
... from selenium import webdriver
...
... browser = SeleniumBrowser(webdriver.Chrome())
... selector = TypeSelector('div')
... operation = FindAll(selector)
... operation.execute(browser)
[...]

It can be used as an element of browser workflows to extract information from web pages, for example: navigate -> click -> wait -> find_all.

__init__(selector: TagSearcher, limit: int | None = None) → None

Initializes the FindAll operation with the specified selector.

Parameters

selectorTagSearcher

Selector used to locate the target element in the document.

limitint, optional

Maximum number of elements to find. Default is None (no limit).