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.