dspk.remote

A client of dspk serve: a GPU server holds the data and runs the sorts; this machine looks and asks.

import dspk

with dspk.remote.Session("192.168.1.20:50051", "me.dspk-identity.pem") as server:
    server.info()                          # who the server is, what this client may do
    server.files("sessions/")              # its data root
    rec = server.open("sessions/a.zarr")   # a dspk.io.Recording, read on the server
    window = rec.read(start=0, stop=30_000)
    server.sort("mountainsort5", "sessions/a.zarr")
    server.wait()                          # follows it (progress, logs on failure)
    server.fetch(server.status()["output"], "a.ms5.sorting.zarr")

The identity file is what dspk clients enroll <name> (--control to run jobs) wrote on the server. Keep it private; it is the client’s key.

Session	A connection to a dspk serve server.

Classes

Session

Session(
    address: str,
    identity: str | PathLike | Path,
    *,
    server_name: str = 'localhost',
) -> Session

A connection to a dspk serve server: a GPU machine that holds the data and runs the sorts.

Use it as a context manager, or close it.

Raises

• ValueError: When address is not an IP:port or the identity file does not exist.
• RuntimeError: When the server cannot be reached or refuses the client.

Examples

>>> import dspk
>>> with dspk.remote.Session("192.168.1.20:50051", "me.dspk-identity.pem") as server:
...     rec = server.open("sessions/a.zarr")
...     window = rec.read(start=0, stop=30_000)

Parameters

• address : str
  The server’s IP:port, such as "192.168.1.20:50051".
• identity : str or os.PathLike
  The client’s identity file, written by dspk clients enroll <name> on the server (--control to run jobs). Keep it private: it is the client’s key.
• server_name : str, default 'localhost'
  A name on the server’s certificate (dspk serve --name adds names).

Session.info

info() -> dict

Who the server is, and who this client is to it.

Returns

• dict — server_name, server_version, peer_name (this client), permission ("read" or "control"), state, has_files, runtime.

Session.files

files(dir: str = '') -> list[dict]

Lists a folder of the server’s data root.

Parameters

• dir : str, default ''
  A folder under the data root; "" for the root itself.

Returns

• list of dict — One per entry: name, kind ("directory", "recording", "sorting", "other"), size, modified_unix, directory.

Session.open

open(path: str, *, source: str | None = None) -> io.Recording

Opens a recording on the server, read over the connection.

A dspk.io.Recording like a local one, for small reads (windows, snippets); work on the whole recording belongs on the server (sort).

Parameters

• path : str
  The recording, under the data root.
• source : str, default None
  One of the file’s sources; by default its default source.

Returns

• dspk.io.Recording

Session.sort

sort(
    sorter: str,
    recording: str,
    *,
    output: str = '',
    params: Mapping[str, str] = {},
    source: str = '',
    probe: str = '',
    start_s: float = 0.0,
    duration_s: float = 0.0,
) -> dict

Starts a sort on the server. Needs a client enrolled with --control.

Parameters

• sorter : str
  A sorter the server has, such as "mountainsort5".
• recording : str
  The recording, under the data root.
• output : str, default ''
  Where the sorting goes; "" puts it next to the recording. Never overwritten.
• params : dict of str to str, default {}
  Sorter options away from their defaults: the flag’s name without --, and its value.
• source : str, default ''
  One of the file’s sources; "" for its default.
• probe : str, default ''
  A probe preset; "" uses the recording’s own geometry.
• start_s : float, default 0.0
  The part to sort, in seconds; 0, 0 sorts it all.
• duration_s : float, default 0.0
  The part to sort, in seconds; 0, 0 sorts it all.

Returns

• dict — The server’s status, as status gives it.

Session.status

status() -> dict

The server’s state and its job’s progress.

Returns

• dict — state ("stopped", "running", "error"), job, stage, step of steps, done of total (in unit), message, output, started_by, started_unix.

Session.stop

stop() -> dict

Stops the running job.

Returns

• dict — The server’s status, as status gives it.

Session.logs

logs(lines: int = 200) -> list[str]

The job’s last log lines.

Parameters

• lines : int, default 200
  How many; 0 for all the server keeps.

Returns

• list of str

Session.fetch

fetch(path: str, dest: str | PathLike | Path) -> tuple[int, int]

Copies a file or folder from the server to this machine.

Parameters

• path : str
  Under the data root: a file, or a folder such as a .sorting.zarr.
• dest : str or os.PathLike
  A new local path; an existing one is never overwritten.

Returns

• int — Files copied.
• int — Bytes copied.

Raises

• ValueError: When dest exists.

Session.close

close() -> None

Ends the connection. Recordings opened from it have their own and stay readable.

Session.wait

wait(
    *,
    poll_s: float = DEFAULT_POLL_S,
    progress: Callable[[dict], None] | None = None,
    timeout_s: float | None = None,
) -> dict

Follows the server’s job until it stops.

Parameters

• poll_s : float, default DEFAULT_POLL_S
  Seconds between status requests.
• progress : callable, default None
progress(status), called at each request while the job runs.
• timeout_s : float, default None
  Give up after this many seconds; by default wait as long as it takes.

Returns

• dict — The last status (see status).

Raises

• RuntimeError: When the job failed, with its last log lines.
• TimeoutError: After timeout_s.

Constants

Name	Type	Value	Description
DEFAULT_POLL_S	float	1.0
DEFAULT_SERVER_NAME	str	'localhost'