uchrom_browser (the web browser)

The web browser is the package uchrom-browser (packages/uchrom-browser). Start it with python -m uchrom_browser STORE (or uchrom_browser.serve()); drive an open browser from Python with uchrom_browser.connect(). The HTTP API is documented in uchrom_browser/API.md.

Starting a server

uchrom_browser.serve(paths: Iterable[str] = (), *, host: str = '127.0.0.1', port: int = 8765, open_browser: bool = True, atlas: str | None = None, hosted: bool = False) → None

Load paths and serve the browser until interrupted.

uchrom_browser.create_app(store: DatasetStore | None = None, atlas: str | None = None, hosted=None)

Build the FastAPI app (imported lazily so data works without FastAPI).

Driving the browser from Python

uchrom_browser.connect(url: str | None = None, timeout: float = 30.0) → Workspace

Connect to a running browser: url > $UCHROM_BROWSER_URL > the last server started > :8765.

class uchrom_browser.Workspace(url: str | None = None, timeout: float = 30.0)

Bases: object

A connection to a running browser server (and, through it, to its open page).

call(action: str, /, **args) → Any

Run one browser action (see tools()) on the active page and return its result (a dict).

capture(pane: str | None = None, path: str | None = None) → Dict[str, Any]

Save a PNG of a view (default: the active one) to path (default: a temporary file).

Returns {"path", "pane", "width", "height", "bytes"} — not the image itself.

dataset()

The ChromData the browser has open (read from the same file, in this process).

describe() → Dict[str, Any]

pages() → List[Dict[str, Any]]

Connected browser pages (the first is the one that receives actions).

selected_cells() → List[str]

Cell ids of the current selection (lasso, focused group or cell); [] when none.

tools() → List[Dict[str, Any]]

The action definitions (name, description, input schema).

class uchrom_browser.BrowserError

Bases: RuntimeError

The server or the page refused an action.

The data layer

class uchrom_browser.DatasetStore

Bases: object

Thread-safe registry of loaded datasets.

add(cd: ChromData, name: str, path: str | None = None) → Dataset

get(dataset_id: str) → Dataset

list() → Sequence[Dataset]

load(path) → Dataset

remove(dataset_id: str) → None