orangeqs.juice.client#

OrangeQS Juice Client API.

Submodules#

Package Contents#

Classes#

Client

Client for OrangeQS Juice.

API#

class orangeqs.juice.client.Client#

Client for OrangeQS Juice.

This class provides methods to interact with components of OrangeQS Juice, like OrangeQS Juice services, messaging, tasks and the database.

Examples#

Instantiating a client.

from orangeqs import juice
client = juice.Client()
async request(service: str, task: orangeqs.juice.task.Task, *, check: bool = False) → orangeqs.juice.task.TaskFuture[orangeqs.juice.task.TaskResultOk] | orangeqs.juice.task.TaskFuture[orangeqs.juice.task.TaskResult]#

Request a task to be executed and return a future for the result.

After this function returns the request was sent to the task manager, but the task may not have been executed yet. Use the returned future to await the task result.

Parameters#

  • service (str): The name of the service to execute the task on.

  • task (Task): The task to execute.

  • check (bool, optional): Whether to check for errors in the task result. If true, raises a TaskExecutionError if the task resulted in an error.

Returns#

  • (TaskFuture): A future that will resolve to the task result. The type of the result depends on the check parameter. If check is True, the future will resolve to a TaskResultOk. If check is False, the future will resolve to a TaskResult (either TaskResultOk or TaskResultError).

Raises#

  • (TaskExecutionError): If check is True and the task resulted in an error. This error is not raised by this function, but by the returned future.

Examples#

Using the default, which is equivalent to check=False:

request = await client.request("my-service", MyTask())
result = await request
if isinstance(result, TaskResultError):
    # Handle error ...
else:
    # Handle success ...

Using check=True:

request = await client.request("my-service", MyTask(), check=True)
try:
    result = await request
    # Handle success ...
except TaskExecutionError as error:
    # Handle error ...
async execute(service: str, task: orangeqs.juice.task.Task, *, check: bool = False) → orangeqs.juice.task.TaskResult#

Execute a task, wait for the result, returning a TaskResult.

This is equivalent to calling await (await client.request(...)). See request() for examples.

Parameters#

  • service (str): The name of the service to execute the task on.

  • task (Task): The task to execute.

  • check (bool, optional): Whether to check for errors in the task result. If true, raises a TaskExecutionError if the task resulted in an error.

Returns#

Raises#

  • (TaskExecutionError): If check is True and the task resulted in an error.

execute_blocking(service: str, task: orangeqs.juice.task.Task, *, check: bool = False, timeout: float | None = None) → orangeqs.juice.task.TaskResult#

Execute a task, wait for the result, returning a TaskResult.

This is the synchronous (blocking) version of execute(). See request() for examples.

Parameters#

  • service (str): The name of the service to execute the task on.

  • task (Task): The task to execute.

  • check (bool, optional): Whether to check for errors in the task result. If true, raises a TaskExecutionError if the task resulted in an error.

  • timeout (float, optional): The maximum time to wait for the task result, in seconds. If None, waits indefinitely. This includes connecting to the task manager, sending the request, executing the task and waiting for the result. Note that if the timeout is exceeded the task is not cancelled, it will continue executing on the service!

Returns#

Raises#

  • (TaskExecutionError): If check is True and the task resulted in an error.

  • (TimeoutError): If a timeout was specified and the task result was not received within the given time.

display_system_info() → None#

Display system information.

Loads system information from disk and prints it in a human-readable format.

ipyclient(service_name: str) → jupyter_client.blocking.client.BlockingKernelClient#

Get an IPython kernel client for a service kernel.

This method caches the ipyclient to avoid creating multiple instance.

Parameters#

  • service_name: Name of the service. Must be present in configuration.

Returns#

  • (BlockingKernelClient): IPython kernel client

Raises#

  • (ValueError): If the service is not found in the connection registry.

ipyclient_async(service_name: str) → jupyter_client.asynchronous.client.AsyncKernelClient#

Get an asynchronous IPython kernel client for a service kernel.

This method caches the ipyclient to avoid creating multiple instance.

Parameters#

  • service_name: Name of the service. Must be present in configuration.

Returns#

  • (AsyncKernelClient): IPython kernel client

Raises#

  • (ValueError): If the service is not found in the connection registry.

display_service_logs(services: str | list[str] | None = None, max_count: int = 10, start: int = 3600, stop: int = 0, level: Literal[DEBUG, INFO, WARNING, ERROR, CRITICAL] = 'WARNING') → None#

Return human readable OrangeQS Juice service logs as dataframe.

Parameters#

  • services: The OrangeQS Juice Services to filter

  • max_count: The number of logs counting back from the most recent entry

  • start: The start time for logs to look up, in seconds from now, default is 3600 , i.e. one hour ago

  • stop: The stop time for logs to look up, in seconds from now, default is 0 , i.e. now

  • level: The minimum log level to filter, default is “WARNING”

display_dashboard_logs(max_count: int = 10, start: int = 3600, stop: int = 0, level: Literal[DEBUG, INFO, WARNING, ERROR, CRITICAL] = 'WARNING', loggers: str | list[str] | None = None) → None#

Return the dashboard logs as a Pandas dataframe.

Parameters#

  • max_count: The number of logs counting back from the most recent entry

  • start: The start time for logs to look up, in seconds from now, default is 3600 , i.e. one hour ago

  • stop: The stop time for logs to look up, in seconds from now, default is 0 , i.e. now

  • level: The minimum log level to filter, default is “WARNING”

  • loggers: The loggers to filter, default is None (i.e. all loggers)

publisher_async(*args: Any, **kwargs: Any) → orangeqs.juice.messaging.protocol.PublisherAsync#
publisher_blocking(*args: Any, **kwargs: Any) → orangeqs.juice.messaging.protocol.PublisherBlocking#
subscriber_async(*args: Any, **kwargs: Any) → orangeqs.juice.messaging.protocol.SubscriberAsync[orangeqs.juice.messaging.protocol.Event]#
subscriber_blocking(*args: Any, **kwargs: Any) → orangeqs.juice.messaging.protocol.SubscriberBlocking[orangeqs.juice.messaging.protocol.Event]#
interrupt_service(service_name: str) → None#

Interrupt an OrangeQS Juice service by name.

Parameters#

  • service_name (str): The name of the service to interrupt. This should correspond to a valid OrangeQS Juice service or the “singleuser” environment.

restart_service(service_name: str, method: Literal[full, partial] = 'full') → None#

Restart an OrangeQS Juice service.

Parameters#

  • service_name (str): The name of the OrangeQS Juice service to restart.

  • method (“full” | “partial”, optional): The restart method to use. Defaults to “full”. - “full”: Restart the container running the service. This will use the newest version of the service image. Uses the Juice Orchestrator RPC. - “partial”: Restart the service process inside the container without restarting the container itself. Uses the Supervisor RPC inside the container.

rebuild_service(service_name: str, mode: Literal[safe, force, dry - run] = 'safe') → None#

Rebuild an OrangeQS Juice service by name.

Parameters#

  • service_name (str): The name of the service to rebuild. This should correspond to a valid OrangeQS Juice service or the “singleuser” environment.

  • mode (“safe” | “force” | “dry-run”, optional): The rebuild mode to use. Defaults to “safe”. - “safe”: Do a dry-run inside the service first, then rebuild if successful. - “force”: Rebuild the service directly without a dry-run. - “dry-run”: Only perform a dry-run inside the service.