Creating an extension package#

This guide explains how to create an OrangeQS Juice extension that can be installed inside the OrangeQS Juice framework.

What is a Juice extension?#

An OrangeQS Juice extension is a Python package that extends the functionality of the OrangeQS Juice framework. It can define new components, such as dashboard pages, configuration schemas, database models, client methods and more. A full list of extension capabilities can be found below:

  • Dashboard pages

  • Configuration schemas

  • Client methods

  • Service implementations

  • Database models

  • Task models

  • Pub/sub models

Setting up a Python package#

As an OrangeQS Juice extension is a standard Python package, start by setting up an empty Python package structure following the Python Packaging User Guide. Ensure that your package is pip installable in your local environment, e.g. using uv pip install -e . from the root folder of your package. For the following sections we assume you have set up a package with the following structure:

juice_extension_example/
├── pyproject.toml
└── src/
    └── juice_extension_example/
        └── __init__.py

Example: Adding a client method#

As a proof of concept, we will add a simple client method to our extension. Client methods are Python functions that are available from the Juice Client.

To add a client method, create a new Python module in your package, e.g. client_methods.py, and define a function that you want to expose as a client method. For example:

src/juice_extension_example/client_methods.py

def hello_world():
    print("Hello, world!")

Next, let’s register this function as a client method in our extension. We do this by defining an entrypoint in pyproject.toml:

pyproject.toml

[project.entry-points."juice.client"]
hello_world = "juice_extension_example.client_methods:hello_world"

Your extension is now ready to be installed in an OrangeQS Juice development environment.

Note

After installing the extension package, this method can be called as follows:

from orangeqs.juice import Client

client = Client()
client.hello_world()