cryosparc.command#

Provides classes and functions for communicating with CryoSPARC’s command servers. Generally should not be used directly.

Classes:

CommandClient([service, host, port, url, ...])

Class for communicating with CryoSPARC's command_core, command_vis and command_rtp HTTP services.

Functions:

make_json_request(client[, url, query, ...])

Similar to make_request, except sends request body data JSON and receives arbitrary response.

make_request(client[, method, url, query, ...])

Create a raw HTTP request/response context with the given command client.
class cryosparc.command.CommandClient(service: str = 'command', host: str = 'localhost', port: int = 39002, url: str = '', timeout: int = 300, headers: dict = {}, cls: Optional[Type[JSONEncoder]] = None)#

Class for communicating with CryoSPARC’s command_core, command_vis and command_rtp HTTP services.

Upon initialization, gets a list of available JSONRPC endpoints and creates corresponding instance methods for each one. Reference of available methods for the command_core service (a.k.a. “cli”) is available in the CryoSPARC Guide.

Parameters:

  • service (str, optional) – Label for CryoSPARC Command service that this instance connects to and communicates with, e.g., command_core, command_vis or command_rtp

  • host (str, optional) – Domain name or IP address of CryoSPARC master. Defaults to “localhost”.

  • port (int, optional) – Command server base port. Defaults to 39002.

  • url (str, optional) – Base URL path prefix for all requests (e.g., “/v1”). Defaults to “”.

  • timeout (int, optional) – How long to wait for a request to complete before timing out, in seconds. Defaults to 300.

  • headers (dict, optional) – Default HTTP headers to send with every request. Defaults to {}.

  • cls (Type[JSONEncoder], optional) – Class to handle JSON encoding of special Python objects, such as numpy arrays. Defaults to None.

service#

label of CryoSPARC Command service this instance connects to and communicates with

Type:

str

Examples

Connect to command_core

>>> from cryosparc.command import CommandClient
>>> cli = CommandClient(
...     host="csmaster",
...     port=39002,
...     headers={"License-ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
... )

Queue a job

>>> cli.enqueue_job(project_uid="P3", job_uid="J42", lane="csworker")
"launched"

Miscellaneous:

Error

alias of CommandError
Error#

alias of CommandError

cryosparc.command.make_json_request(client: CommandClient, url='', *, query={}, data=None, headers={}, _stacklevel=3)#

Similar to make_request, except sends request body data JSON and receives arbitrary response.

Parameters:

  • client (CommandClient) – command client instance

  • url (str, optional) – URL path to append to the client’s initialized root URL. Defaults to “”.

  • query (dict, optional) – Query string parameters. Defaults to {}.

  • data (any, optional) – JSON-encodable request body. Defaults to None.

  • headers (dict, optional) – HTTP headers. Defaults to {}.

Yields:

http.client.HTTPResponse – Use with a context manager to get HTTP response

Raises:

CommandError – General error such as timeout, URL or HTTP

Example

>>> from cryosparc.command import CommandClient, make_json_request
>>> cli = CommandClient()
>>> with make_json_request(cli, url="/download_file", data={'path': '/file.txt'}) as response:
...     data = response.read()
cryosparc.command.make_request(client: CommandClient, method: str = 'POST', url: str = '', *, query: dict = {}, data=None, headers: dict = {}, _stacklevel=2)#

Create a raw HTTP request/response context with the given command client.

Parameters:

  • client (CommandClient) – command client instance

  • method (str, optional) – HTTP method. Defaults to “POST”.

  • url (str, optional) – URL to append to the client’s initialized URL. Defaults to “”.

  • query (dict, optional) – Query string parameters. Defaults to {}.

  • data (any, optional) – Request body data. Usually in binary. Defaults to None.

  • headers (dict, optional) – HTTP headers. Defaults to {}.

Raises:

CommandError – General error such as timeout, URL or HTTP

Yields:

http.client.HTTPResponse – Use with a context manager to get HTTP response

Example

>>> from cryosparc.command import CommandClient, make_request
>>> cli = CommandClient()
>>> with make_request(cli, url="/download_file", query={'path': '/file.txt'}) as response:
...     data = response.read()