Skip to content

README.md

Latest commit

 

History

History
113 lines (91 loc) · 3.6 KB

README.md

File metadata and controls

113 lines (91 loc) · 3.6 KB

rom-runtime

Python bindings for the ROM browser-like runtime.

This package exposes a thin Python API on top of ROM:

  • eval()
  • eval_async()
  • eval_json()
  • goto()
  • set_content()
  • content()
  • evaluate()
  • wait_for_selector()
  • wait_for_function()
  • click()
  • fill()
  • text_content()
  • inner_html()
  • locator()
  • surface_snapshot()
  • fingerprint_probe()
  • run_fingerprintjs_harness()
  • fingerprintjs_version()

It prefers a native PyO3 extension when available and falls back to the ROM CLI bridge otherwise.

Install

pip install rom-runtime

Usage

from rom import RomRuntime, has_native_binding

runtime = RomRuntime(
    {
        "href": "https://example.test/",
        "referrer": "https://referrer.example/",
        "cors_enabled": False,
        "proxy_url": None,
    }
)
href = runtime.eval_async("(async () => location.href)()")
snapshot = runtime.surface_snapshot()

print("native:", has_native_binding())
print(href)
print(snapshot["fetch"])

runtime.eval_async("(async () => { globalThis.__rom_value = 42; return 'ok'; })()")
print(runtime.eval_async("(async () => String(globalThis.__rom_value))()"))

runtime.set_content(
    '<div id="app"><input id="name" /><button id="go">Go</button><span id="out"></span></div>'
    '<script>document.querySelector("#go").addEventListener("click",()=>{document.querySelector("#out").textContent=document.querySelector("#name").value;});</script>'
)
runtime.fill("#name", "ROM")
runtime.click("#go")
print(runtime.text_content("#out"))

Config keys use the Rust runtime field names, so use snake_case such as cors_enabled and proxy_url. cors_enabled is False by default. When the native extension is loaded, one RomRuntime instance keeps JS globals alive across multiple eval() and eval_async() calls. The page-like helpers such as goto(), set_content(), click(), and wait_for_selector() require the native extension because CLI bridge mode is stateless across calls. For cookie seeding, the wrapper accepts serialized cookie_store, a raw cookie header string, or a cookies alias with string/object/array inputs and normalizes them automatically. For storage seeding, the wrapper accepts local_storage and session_storage as serialized JSON objects, Python dicts, or entry arrays such as [('VerifyAuthToken', 'seeded')]. The default navigator surface is Chrome-like, including navigator.userAgent, navigator.vendor, and navigator.userAgentData.

Optional native build from source

python -m pip install maturin
python -m maturin build --manifest-path bindings/gom-python/Cargo.toml --release

Tagged GitHub releases build and publish wheels for Linux, Windows, and macOS, plus an sdist for source installs.

Common methods

  • eval()
  • eval_async()
  • eval_json()
  • goto(url, options=None)
  • set_content(html, options=None)
  • content()
  • evaluate(js_expression, arg=None)
  • wait_for_selector(selector, options=None)
  • wait_for_function(js_expression, arg=None, options=None)
  • click(selector, options=None)
  • fill(selector, value, options=None)
  • text_content(selector, options=None)
  • inner_html(selector, options=None)
  • locator(selector)
  • surface_snapshot()
  • fingerprint_probe()
  • run_fingerprintjs_harness()
  • fingerprintjs_version()

Environment

  • ROM_FORCE_CLI_BRIDGE=1: disable the native path and force CLI fallback
  • ROM_BRIDGE_BIN: explicit path to the rom_bridge executable
  • ROM_BRIDGE_CWD: working directory used by the CLI fallback

More docs