Client#

The Client is the standard interface for users to interact with the OrangeQS Juice installation. This includes the running services, databases, etc. The Client provides APIs to interact with these components. These standard APIs are used by lab operators, services and the dashboard to communicate with Juice.

Adding functionality of your extension as methods to the Juice Client makes the features of your extension easily discoverable for users.

Adding Client methods#

This guide explains how to add methods of your extension to the Juice Client API.

To add a method to the Juice Client, you need to:

  1. Define a method to be added to the client

  2. Configure the "juice.client" entry point in your pyproject.toml to tell Juice where to find your method.

  3. Reinstall your extension to apply the entry point configuration.

Let’s start by defining a function for the client method.

from orangeqs.juice import Client

# Define the function to be injected as method
def client_method(client: Client, argument: str):
    print(f"Calling `client_method` on {client} with {argument}")

As the function will act on an instance of client, it should take it as the first argument. Note that when you call this method later on, the call signature will be client.client_method(argument: str).

Injecting functions vs methods

In Python, methods refer to functions that have been defined as attributes of objects. Methods act on the object they have been defined on, taking self as the first argument. However, the callable client_method we have just defined is a function instead of an object.

To address this, OrangeQS Juice will convert any function where the first argument has a Client type annotation or is named client to a method. This ensures that the client instance is passed when the method is called.

OrangeQS Juice also supports injecting function that do not depend on a client instance. It will inject these functions directly. This means that the following code works as well:

# Define as a function
def client_function(argument: str):
    print(f"Calling function with {argument}")

# Later, call the function as if it were a method
client.client_function("argument")

Next, let’s add an entry point to expose your method to the OrangeQS Juice client. You can do this by adding the following to your pyproject.toml:

# pyproject.toml

# Tell Juice where to find Client methods
[project.entry-points."juice.client"]
# Expose `client_method` as example_client_method on the Client
example_client_method = "juice_extension_example:client_method"

When a Client is instantiated, Juice will load all "juice.client" entry points and add the listed methods to the client. To prevent method name collisions it’s a good practice to prepend method names with your extension name, like we have done with example_.

Finally, let’s reinstall our packages to make the entry point available. Since entry points have to be installed by your package manager (e.g. pip), you have to explicitly re-install your extension if you add or modify entry points. This even holds for packages that have been installed editably! To do this using pip, run pip install -e .. See the setuptools entry points documentation for more information on entry points.

After re-installing, we can test our injected method.

from orangeqs import juice

client = juice.Client()
client.example_client_method("argument")
# > Calling `client_method` on {client} with {argument}
On this page