Documentation
Python client
wisp.py is a small client for the local API. It uses the Python standard library only and is installed with Wisp in resources\connect.
Set up
No pip install needed. You need Python 3.8 or newer. Add the connect folder to sys.path and import it:
import os, sys
sys.path.insert(0, os.path.expandvars(r"%LOCALAPPDATA%\Programs\Wisp\resources\connect"))
from wisp import Wisp
w = Wisp() # starts Wisp hidden if it is not running
tab = w.open("https://example.com", profile="Work")
print(w.text(tab))
snap = w.snapshot(tab) # elements with refs
w.click(tab, ref=snap["elements"][0]["ref"])
w.screenshot(tab, path="shot.png")
w.close(tab)Everything runs in the background: no window comes to the front and no mouse or keyboard is used. Wisp() reads the port and token from %APPDATA%\Wisp\api.json; if Wisp isn’t running it starts it hidden and waits up to about 30 seconds for the API. Pass autostart=False to raise an error instead.
Methods
| Method | Does |
|---|---|
open(url, activate=False, profile=None) | Open a background tab, wait for load, return its id. |
close(tab) | Close a tab. |
goto(tab, url), back(tab), reload(tab) | Navigate. |
text(tab, selector=None, max_chars=None) | Visible text of the page or one element. |
html(tab, selector=None) | HTML of the page or one element. |
snapshot(tab, viewport_only=None) | Interactive elements with refs like w12. |
click(tab, ref=, selector=, text=, x=, y=) | Click an element or a point. |
type(text, tab, ref=, selector=, submit=, clear=) | Type into an element (replaces its content unless clear=False). |
key(key, tab), scroll(tab, dy=None) | Press a key; scroll. |
wait(tab, selector=, text=, ms=, timeout=) | Wait for an element, text, or time. |
eval(code, tab) | Run JavaScript, return the value. |
screenshot(tab, path=None, full_page=None) | Save a PNG to path, or return PNG bytes. |
cdp(method, params=None, tab=None) | Raw Chrome DevTools Protocol command. |
status(), tabs(), profiles() | Information. |
show(), hide(), quit() | Window and app. |
rpc(method, **params) | Call any API method directly. |
Methods that take tab use the tab you used last when you leave it out. Errors from Wisp raise WispError.
Another example
tab = w.open("https://news.ycombinator.com")
w.click(tab, text="new") # click by visible text
w.wait(tab, selector=".athing")
titles = w.eval("[...document.querySelectorAll('.titleline > a')].map(a => a.textContent)", tab=tab)
print(titles[:5])Environment variables
WISP_EXE: full path toWisp.exe, if Wisp is not in the default install folder.WISP_DATA_DIR: talk to a Wisp started with that data folder (for testing; the default is%APPDATA%\Wisp).