Documentation menu · Python client

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:

Python
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

MethodDoes
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

Python
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 to Wisp.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).