Lab repository#

The lab repository is the central place for users to store shared code, define external dependencies and manage configurations for an OrangeQS Juice installation. The lab repository is a standard Python package that is installed for all users and services. An empty default lab repository comes preinstalled with OrangeQS Juice at shared/lib/lab.

This guide will take you to the basic steps of using the lab repository.

Setting up version control#

This section guides you through setting up version control for your lab repository using Git.

A version control systems tracks changes to your code, allowing you to collaborate with others and revert to previous versions if needed. Version control helps prevent data loss, encourages teamwork, and improves the overall reliability of your development process. Refer to the About Version Control section of the Pro Git book for more information.

We will set up version control using Git. We will assume you have opened and logged in to the OrangeQS Juice JupyterHub from your browser.

Start by opening up a terminal from the JupyterHub launcher. Next, navigate to the lab folder in the shared library folder by executing the following command:

cd ~/shared/lib/lab

In the lab directory, create an empty Git repository, configure your email and name, add the files that are already there to Git, and finally commit them with a message.

# Initialize repository
git init -b main

# Configure your personal details so git knows who you are
git config --global user.email "[email protected]"
git config --global user.name "Your Name"

# Add the default files to git
git add .

# Commit the files with an attached message
git commit -m 'add default lab repository'

We strongly advise you to synchronize your repository with a remote service like GitLab or GitHub. The steps above are the very basics of Git, refer to the full Git Book for more information about Git and to learn about all its features.

Adding code#

This section explains how to add code that can be used by other users and services.

Adding common code to the lab repository is useful for multiple reasons:

  • It is version controlled, so you can always go back to a previous version.

  • It reduces duplication of the same code.

  • It is automatically available from anywhere.

  • It prompts you to write general, reusable code.

Code placed in the lab repository is available to be imported by any user or service. As mentioned in the introduction, the lab repository is a standard Python package. The lab Python package is installed for every user and service. By adding a .py file to the src/lab folder, the module can be imported from anywhere.

As an example, let’s create utilities.py in src/lab with the following contents:

# src/lab/utilities.py

def useful_function():
    return "answer"

Now, open up a new notebook from the JupyterHub launcher and let’s import and call this function:

# From a notebook

import lab.utilities
lab.utilities.useful_function()  # <- returns "answer"

Adding dependencies#

This section explains how to install dependencies that can be used by other users and services.

Additional dependencies can be installed by configuring them as dependencies in the lab repository. Dependencies should be added to the pyproject.toml file in the lab folder. This file already exists. As the lab repository is automatically installed by OrangeQS Juice, so will its dependencies.

As an example, let’s add numpy as an additional dependency.

# pyproject.toml

dependencies = [
    "orangeqs-juice-core",
    # Add additional dependencies here
    "numpy",  # <- Added this line.
]

Now we have to let OrangeQS Juice to reinstall the lab package, to install the new dependencies. This can be done in two ways:

  1. Restart your personal server from the Hub Control Panel. You can find this panel under File > Hub Control Panel from the JupyterHub UI.

  2. Reinstall the package from the terminal using uv. To do this, open a terminal and navigate to the lab repository using cd ~/shared/lib/lab. Next, reinstall the package using uv pip install -e .. Finally, restart your notebook kernel or Python program.

Now, we can import numpy from a notebook:

import numpy as np
np.arange(10)

Refer to dependencies and requirements in the Python Packaging User Guide for more information about dependencies.

Hint

If you make modifications to your lab repository, you should consider which parts of OrangeQS Juice need to be restarted to reflect your changes. Below is a guideline which lists some common cases:

  • Changing a Python file which is used in:

    • a service: Restart the service.

    • your notebook: Restart your notebook kernel.

  • Changing a dependency which is used in:

    • a service: Restart the service.

    • your notebook: There are two options:

      • Restart your personal server from the Hub Control Panel.

      • Reinstall the lab package using uv pip install -e . from the ~/shared/lib/lab folder and restart your notebook.

Next steps#

This guide has shown you the basics of the lab repository. The lab repository is able to do much more than that, refer to the list below to learn about more of its features:

  • It is a good idea to extend pyproject.toml with a description, author information, readme, etc. Refer to Writing your pyproject.toml of the Python Packaging User Guide. Warning: Do not change the name of the package if you do not know what you are doing!.

  • The lab repository is a Python Package and can thus be used as an OrangeQS Juice Extension Package. This allows you to manage configurations, add services, dashboard widgets and more, all from within your version controlled package. Refer to the Extensions guide for more information. Note that creating the package and setting up a development environment is not necessary, as the lab package is already installed in an OrangeQS Juice installation.