Skip to content

Python API reference

The reference documents the public herdr_client surface: synchronous and asynchronous clients, long-lived event subscriptions, schema-derived result types and protocol metadata.

Use the client pages when you need an operation signature. Use the types page when you need to understand the dictionary returned by an operation.

  • Clients

    Create a sync or async client, inspect workspaces and panes, send input, read output and wait for matches.

    Open the client API

  • Subscriptions

    Keep a Unix socket open and consume pushed event envelopes with a context manager.

    Open the subscription API

  • Types

    Browse typed request parameters, response dictionaries, event envelopes and JSON aliases.

    Browse the types

  • Exceptions

    Handle transport failures and error envelopes without losing Herdr's error code or message.

    Browse exceptions

  • Protocol coverage

    See the pinned schema version, canonical method coverage and convenience wrappers.

    Inspect protocol coverage

Design guarantees

Guarantee Meaning
Sync/async parity Both clients expose the same operation names, parameters and result models.
Dictionary compatibility Wire results remain ordinary dictionaries at runtime.
Typed boundaries Public signatures use TypedDict, Literal and recursive JSON aliases.
Local transport Requests use newline-delimited JSON over a Unix socket.
Forward compatibility Unknown response fields are retained instead of discarded.

Typical flow

from herdr_client import HerdrClient

client = HerdrClient()
workspaces = client.workspace_list()
panes = client.pane_list(workspaces["workspaces"][0]["id"])
output = client.pane_read(panes["panes"][0]["id"])

For a first request and socket resolution rules, start with the getting started guide.