isoautomate 0.1.4

Official Python SDK for the isoAutomate Sovereign Browser Infrastructure, providing connectivity to the isoFleet engine.

isoAutomate Python SDK

The Sovereign Browser Infrastructure & Orchestration Platform

---

Installation

Install the SDK via pip:

pip install isoautomate

Configuration

The SDK requires a connection to a Redis instance to communicate with the browser engine. You can configure this either via an environment file (.env) or directly in your Python code.

Method A: Environment Variables (.env) Create a .env file in your project root. This is the recommended way to keep credentials out of your source code. You can use either a single connection string or individual fields.

# Individual Fields
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=yourpassword
REDIS_DB=0
REDIS_SSL=False

# OR Single Redis URL (overrides individual fields if present)
# REDIS_URL=rediss://:password@host:port/0

Method B: Direct Initialization

You can pass connection details directly when creating the BrowserClient instance.

Using individual arguments:

from isoautomate import BrowserClient

browser = BrowserClient(
    redis_host="localhost",
    redis_port=6379,
    redis_password="yourpassword",
    redis_db=0,
    redis_ssl=True
)

Using a Redis URL:

from isoautomate import BrowserClient

browser = BrowserClient(
    redis_url="rediss://:password@host:port/0"
)

Usage Examples

Browser sessions are managed through the BrowserClient. To ensure that browser resources are cleaned up properly on the server, we highly recommend using the Context Manager approach.

1. Context Manager (Recommended)

Using the with statement ensures that the browser is automatically released back to the fleet, even if your script crashes or an error occurs.

from isoautomate import BrowserClient

# The context manager handles browser.release() automatically
with BrowserClient() as browser:
    # Acquire the browser instance
    browser.acquire(browser_type="chrome_profiled", video=True)
    
    browser.open_url("https://example.com")
    browser.assert_text("Example Domain")

    # Video URL is available after the context block ends
    print(f"Session video: {browser.video_url}")

2. Manual Control

If you prefer manual control, you must call .release() inside a finally block to prevent "ghost" browsers from staying active on your worker(watchdog in the engine/worker makes the browsers available after 120s or the time you gave when starting the worker/engine).

from isoautomate import BrowserClient

browser = BrowserClient()
try:
    browser.acquire(browser_type="chrome")
    browser.open_url("https://example.com")
finally:
    # Crucial: Always release to free up slots for other tasks
    browser.release()

The Acquire Method

The acquire() method is used to claim a browser from your remote fleet. It supports several parameters to customize your environment.

Parameters

Parameter	Type	Default	Description
browser_type	str	"chrome"	The browser to use: chrome, brave, opera, or their _profiled variants for CDP mode.
video	bool	False	When True, starts an MP4 recording of the browser session.
record	bool	False	When True, records DOM events for session replay.
profile	str | bool	None	Enables persistence for cookies, logins, and site data.

Understanding Persistence (Profiles)

Persistence allows you to resume sessions so you don't have to log in to websites repeatedly.

• Managed Profile (profile=True): The SDK manages a persistent ID for you locally. It creates a .iso_profiles folder in your project to remember which browser belongs to this project.
• Custom Profile (profile="my_account_1"): You provide a specific string. This is best for managing multiple different accounts. Any script using the same string will share the same cookies and history.

# Example: Using a named profile for a specific social media account
browser.acquire(profile="twitter_marketing_account")

Browser Actions

Once you have acquired a browser, you can control it using the following methods.

1. Navigation

Method	Arguments	Description
open_url(url)	url (str)	Navigates the browser to the specified website.
reload(ignore_cache, script)	ignore_cache (bool=True), script (str=None)	Force reloads the page. ignore_cache ensures a fresh fetch. script runs JS immediately after the reload.
refresh()	None	Reloads the current page (standard refresh).
go_back()	None	Navigates to the previous page in history.
go_forward()	None	Navigates to the next page in history.
internalize_links()	None	Forces all links on the current page to open in the current tab instead of a new one.
get_navigation_history()	None	Returns the list of URLs in the current session's history.

# Basic navigation
browser.open_url("https://isoautomate.com")

# Hard reload with a custom script to hide a banner
browser.reload(ignore_cache=True, script="document.querySelector('.banner').style.display='none';")

# Prevent new tabs from popping up
browser.internalize_links()

2. Mouse Interactions

These methods handle standard web-element interactions using the browser's automation engine.

Method	Arguments	Description
click(selector, timeout)	selector (str), timeout (int=None)	Clicks an element. timeout (seconds) determines how long to wait for the element to appear.
click_if_visible(selector)	selector (str)	Attempts to click an element only if it is visible. Fails silently if not found.
click_visible_elements(selector, limit)	selector (str), limit (int=0)	Clicks all visible instances of a selector. limit caps the clicks (0 for all).
click_nth_visible_element(selector, number)	selector (str), number (int=1)	Clicks the specific visible instance (e.g., 2nd button) based on the number provided.
click_link(text)	text (str)	Finds a link by its visible text and clicks it.
click_active_element()	None	Clicks whichever element currently holds the browser's focus.
double_click(selector)	selector (str)	Performs a standard double-click on the targeted element.
right_click(selector)	selector (str)	Performs a context (right) click on the targeted element.
hover(selector)	selector (str)	Moves the mouse cursor over an element without clicking.
nested_click(parent_selector, selector)	parent_selector (str), selector (str)	Finds the parent first, then locates and clicks the child element inside it.
click_with_offset(selector, x, y, center)	selector (str), x, y (int), center (bool=False)	Clicks at relative coordinates. If center=True, x/y are offsets from the element's middle.
drag_and_drop(drag_selector, drop_selector)	drag_selector (str), drop_selector (str)	Picks up the first element and drops it onto the second element via JS events.

# Click a button but wait up to 15 seconds for it to load
browser.click("#submit-btn", timeout=15)

# Click the 2nd visible 'Add to Cart' button found on a page
browser.click_nth_visible_element("button.add-to-cart", number=2)

# Click exactly 5 pixels from the left and 10 pixels from the top of an element
browser.click_with_offset("#map-canvas", x=5, y=10)

3. Keyboard and Input

These methods provide granular control over how text is entered and how forms are processed, ranging from high-speed data entry to human-simulated typing.

Method	Arguments	Description
type(selector, text, timeout)	selector, text (str), timeout (int=None)	Rapidly enters text into a field. Optional timeout waits for the field to appear.
press_keys(selector, text)	selector, text (str)	Simulates individual key presses. This is slower and mimics human behavior to avoid detection by basic scripts.
send_keys(selector, text)	selector, text (str)	Standard automation method to send raw keys to an element.
set_value(selector, text)	selector, text (str)	Directly sets the value attribute of an element via the browser's internal API.
clear(selector)	selector (str)	Deletes all current text/content within an input or textarea element.
clear_input(selector)	selector (str)	Specifically targets <input> fields to reset their state.
submit(selector)	selector (str)	Triggers the submit event for the form containing the specified element.
focus(selector)	selector (str)	Sets the browser's active focus to the specified element, triggering "onfocus" events.

Usage Example:

# Use standard 'type' for speed on non-sensitive fields
browser.type("#search", "isoAutomate documentation", timeout=5)

# Use 'press_keys' for fields that listen for keyup/keydown events (like passwords)
browser.press_keys("input[name='password']", "securePassword123")

# Clear a field before updating it
browser.clear("#email-field")
browser.type("#email-field", "[e-mail]")

# Focus and submit
browser.focus("#login-btn")
browser.submit("#login-form")

4. GUI Actions (OS-Level Control)

GUI actions operate at the hardware level. Instead of sending Javascript events through the browser engine, they move a virtual mouse and press virtual keys on the remote machine's operating system.

Note: These actions require a _profiled browser engine (e.g., chrome_profiled).

Method	Arguments	Description
gui_click_element(selector, timeframe)	selector (str), timeframe (float=0.25)	Physically moves the OS cursor to the element's coordinates and clicks. timeframe controls the speed of the cursor movement.
gui_click_x_y(x, y, timeframe)	x, y (int), timeframe (float=0.25)	Physically clicks on raw pixel coordinates on the screen.
gui_hover_element(selector)	selector (str)	Physically moves the OS cursor to hover over an element.
gui_drag_and_drop(drag, drop, timeframe)	drag, drop (str), timeframe (float=0.35)	Performs a hardware-level press, drag movement, and release gesture.
gui_write(text)	text (str)	Direct hardware-level keyboard input. This types into the element that currently has the OS focus.
gui_press_keys(keys_list)	keys_list (list)	Sends a list of specific hardware keys (e.g., ['control', 'c']).
gui_click_captcha()	None	Automatically locates the verification checkbox in common captcha widgets and performs a physical OS-level click.
solve_captcha()	None	A high-level trigger that handles the OS-level movement required to check verification boxes.

High-Fidelity Examples:

# Perform a hardware-level click on a button to mimic real human interaction
browser.gui_click_element("#login-submit", timeframe=0.5)

# Drag a physical slider or element
browser.gui_drag_and_drop("#source-box", "#target-bin")

# Type using the OS virtual keyboard (useful for bypassing JS-level listeners)
browser.focus("#comment-box")
browser.gui_write("Typing at the hardware level.")

# Handle verification checkboxes automatically
browser.solve_captcha()

5. Selects & Dropdowns

These methods simplify interacting with standard HTML <select> elements and custom dropdown menus.

Method	Arguments	Description
select_option_by_text(selector, text)	selector, text (str)	Selects an option from a dropdown list based on the visible text shown to the user.
select_option_by_value(selector, value)	selector, value (str)	Selects an option based on its internal HTML value attribute.
select_option_by_index(selector, index)	selector (str), index (int)	Selects an option based on its position in the list (starting from 0).

Examples:

# Select "United States" from a country list by its visible name
browser.select_option_by_text("#country-select", "United States")

# Select an option where the HTML looks like <option value="USD">Dollar</option>
browser.select_option_by_value("#currency", "USD")

# Select the first option in a list
browser.select_option_by_index("#category", 0)

6. Window & Tab Management

These methods allow you to orchestrate multiple browser contexts, switch between tabs, and control the physical dimensions of the browser window.

Method	Arguments	Description
open_new_tab(url)	url (str)	Opens a new browser tab and navigates to the specified URL. Automatically switches focus to the new tab.
open_new_window(url)	url (str)	Opens a completely new browser window instance and navigates to the URL.
switch_to_tab(index)	index (int=-1)	Switches the active focus to a different tab. 0 is the first tab, -1 is the most recently opened tab.
switch_to_window(index)	index (int=-1)	Switches focus to a different window instance.
close_active_tab()	None	Closes the current tab. Focus will automatically shift to the next available tab.
maximize()	None	Expands the browser window to fill the entire screen.
minimize()	None	Minimizes the browser window to the taskbar/dock.
medimize()	None	Resizes the window to a medium, standard size (Requires _profiled engine).
tile_windows()	None	Organizes all open windows into a grid pattern on the screen (Requires _profiled engine).
set_window_size(w, h)	width (int), height (int)	Sets the browser viewport to a specific pixel resolution (e.g., 1280x720).

Window Control Examples:

# Open a second site in a new tab
browser.open_new_tab("https://google.com")

# Switch back to the original tab (first one)
browser.switch_to_tab(0)

# Set a specific resolution for responsive testing
browser.set_window_size(375, 812) # iPhone X dimensions

7. Data Extraction (Getters)

These methods allow you to retrieve data from the remote browser and return it to your local Python script for processing.

Method	Arguments	Description
get_text(selector)	selector (str="body")	Retrieves the visible text content of an element. Defaults to the entire page body.
get_title()	None	Returns the current page title as shown in the browser tab.
get_current_url()	None	Returns the absolute URL of the page currently being viewed.
get_page_source()	None	Returns the full raw HTML source code of the current page as a string.
save_page_source(name)	name (str="source.html")	Downloads the full raw HTML source code and saves it to a local file.
get_html(selector)	selector (str=None)	Returns the inner HTML of a specific element. If no selector is provided, returns the <html> content.
get_attribute(selector, attr)	selector, attr (str)	Retrieves the value of a specific HTML attribute (e.g., src, href, value).
get_element_attributes(sel)	selector (str)	Returns a dictionary containing all attributes of the targeted element.
get_user_agent()	None	Returns the User Agent string currently being used by the browser.
get_cookie_string()	None	Returns all cookies for the current domain formatted as a single string.
get_element_rect(sel)	selector (str)	Returns a dictionary with the element's position and size (x, y, width, height).
get_window_rect()	None	Returns the browser window's current dimensions and position.
is_element_visible(sel)	selector (str)	Returns True if the element is currently visible on the screen.
is_text_visible(text)	text (str)	Returns True if the specified text is visible anywhere on the page.
get_performance_metrics()	None	Returns detailed network and rendering performance metrics from the browser engine.

Data Extraction Examples:

# Get the price of a product
price = browser.get_text(".product-price")

# Extract a link from a button
download_url = browser.get_attribute("#download-link", "href")

# Save the full HTML for offline parsing
browser.save_page_source("debug_page.html")

# Check visibility before interacting
if browser.is_element_visible("#cookie-consent"):
    browser.click("#accept-all")

8. Cookies & Session Storage

These methods provide direct control over browser cookies and storage, allowing you to manage sessions, bypass logins, or clear tracking data manually.

Method	Arguments	Description
get_all_cookies()	None	Returns a list of dictionaries containing all cookies for the current domain.
get_cookie_string()	None	Returns all cookies formatted as a single string (useful for header injection).
add_cookie(cookie_dict)	cookie_dict (dict)	Injects a new cookie into the current session.
delete_cookie(name)	name (str)	Deletes a specific cookie by name.
clear_cookies()	None	Clears all cookies from the current browser session.
save_cookies(name)	name (str)	Saves current cookies to a local JSON file.
load_cookies(name)	name (str)	Loads cookies from a local JSON file.
get_local_storage_item(key)	key (str)	Retrieves a specific value from localStorage.
set_local_storage_item(key, value)	key, value (str)	Sets a specific key-value pair in localStorage.

Usage Examples:

# Save cookies to a file for later use
cookies = browser.get_cookies()

# Manually inject a session cookie to bypass login
browser.add_cookie({
    "name": "session_id",
    "value": "xyz123",
    "domain": "example.com"
})

# Clear all storage to start a clean session
browser.delete_all_cookies()
browser.clear_local_storage()

9. Wait & Verification (Assertions)

These methods are essential for handling dynamic content. They ensure your script waits for elements to load before interacting, preventing "Element Not Found" errors.

Method	Arguments	Description
sleep(seconds)	seconds (float)	Performs a hard pause for the specified number of seconds.
wait_for_element(selector, timeout)	selector (str), timeout (int=None)	Pauses execution until the element appears in the DOM.
wait_for_text(text, timeout)	text (str), timeout (int=None)	Pauses execution until the specific text is visible on the page.
wait_for_network_idle()	None	Pauses execution until network activity stops (useful for SPAs).
assert_element(selector)	selector (str)	Validates that an element exists. Raises an AssertionError if not found.
assert_text(text, selector)	text (str), selector (str="body")	Validates that specific text exists within a chosen element (default: whole page).

Usage Examples:

# Wait for a slow-loading dashboard to appear
browser.wait_for_element("#dashboard-main", timeout=20)

# Wait for page network activity to settle
browser.wait_for_network_idle()

# Verify that login was successful
browser.assert_text("Welcome back, User!", selector="h1")

# Hard pause (use sparingly)
browser.sleep(2.5)

10. Scripting & Advanced Features

These methods allow you to extend the SDK's capabilities by executing custom logic directly within the browser context or retrieving advanced metadata.

Method	Arguments	Description
execute_script(script)	script (str)	Executes raw Javascript within the current page context.
evaluate(expression)	expression (str)	Evaluates a JS expression and returns the value.
execute_cdp_cmd(cmd, params)	cmd (str), params (dict)	God Mode: Executes raw Chrome DevTools Protocol commands directly.
get_mfa_code(totp_key)	key (str)	Generates a 2FA/TOTP code from a secret key.
enter_mfa_code(selector, key)	selector, key	Generates a 2FA code and types it into the selector.
grant_permissions(perms)	perms (list)	Grants browser permissions (e.g., ['clipboardReadWrite']).
get_performance_metrics()	None	Returns a detailed dictionary of Chrome performance logs.
highlight(selector)	selector (str)	Visually highlights an element (useful for debugging/video).
internalize_links()	None	Rewrites target="_blank" links to open in the current tab.
get_user_agent()	None	Retrieves the current browser's User Agent string.

Usage Examples:

# Execute JS to get the value of a complex hidden variable
user_id = browser.execute_script("return window.appConfig.currentUserId;")

# GOD MODE: Clear browser cache directly via CDP
browser.execute_cdp_cmd("Network.clearBrowserCache", {})

# GOD MODE: Emulate a mobile device metrics
browser.execute_cdp_cmd("Emulation.setDeviceMetricsOverride", {
    "width": 375, "height": 812, "deviceScaleFactor": 3, "mobile": True
})

# Highlight an element before clicking it for a better video recording
browser.highlight("#buy-now-button")
browser.click("#buy-now-button")

11. Full Example: Social Media Automation

This example demonstrates a complete workflow: using persistence to stay logged in, performing high-fidelity GUI clicks to bypass detection, and extracting data.

from isoautomate import BrowserClient
import time

# Use the context manager for automatic cleanup
with BrowserClient() as browser:
    # 1. Acquire a browser with a persistent profile for "User_Alpha"
    # We use 'chrome_profiled' to enable hardware-level GUI actions
    browser.acquire(
        browser_type="chrome_profiled", 
        profile="User_Alpha", 
        video=True
    )

    # 2. Navigate and wait for content
    browser.open_url("https://example-social-media.com/login")
    
    # 3. Handle login if not already logged in
    if browser.is_text_visible("Sign In"):
        browser.type("#username", "my_bot_user")
        browser.press_keys("#password", "secure_pass_123")
        
        # Use GUI click for the final submit to mimic human behavior
        browser.gui_click_element("#login-btn")
        
        # Wait for the dashboard to confirm successful login
        browser.wait_for_element(".dashboard-feed", timeout=15)

    # 4. Interact with the feed
    browser.hover(".first-post")
    browser.click(".like-button")
    
    # 5. Extract data to your local script
    post_stats = browser.get_text(".post-stats")
    print(f"Current Post Stats: {post_stats}")

    # 6. Session video is automatically saved on the server
    print(f"View execution recording at: {browser.video_url}")

# Connection is closed here, and the browser is released back to the fleet

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Contributing

We welcome contributions to the isoAutomate Python SDK! If you'd like to help improve the platform, please follow these steps:

1. Fork the repository.
2. Create a new feature branch (git checkout -b feature/your-feature-name).
3. Commit your changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature/your-feature-name).
5. Open a Pull Request.

For major changes, please open an issue first to discuss what you would like to change.

---

Built for the Sovereign Web. Powered by isoAutomate.

Official Website • Full API Reference • Support