Skip to content
Documentation

Python SDK

Raise SDK is a Python module designed to allow developers to interact with the core functionalities of the RAISE project.

Open View.

In the current version (0.2.6), the SDK includes one submodule, revo (i.e. Remote Execution Validation Operations), and a utils folder.

  • REVO (Remote Execution Validation Operations)
    The REVO module is designed to implement the core functionalities of the RAI Processing Script Manager, enabling seamless execution and management of Python scripts for experiments. It is designed to automate key tasks such as managing dependencies, handling dataset selection, and running the main Python script, while also ensuring proper validation throughout the process. By integrating these features, REVO ensures that experiments are executed efficiently and with accurate logging, while validating the execution environment and providing detailed results for further analysis.
  • Utils
    The utils/ folder serves as a collection of utilities that provide reusable, convenient, and well-structured functions to simplify common tasks across the application. These functions are designed to handle tasks such as file and folder operations, user interactions, and system-level dialogs.

Installation

You can install raise_sdk directly from PyPI using pip:

Terminal window
pip install raise_sdk

To verify that the installation was successful, you can check if the module is installed and accessible by running a simple Python command. Open a Python shell and try to import the module:

import raise_sdk

If no errors are raised, the package is installed and ready to use.

Troubleshooting

If you encounter any issues during installation:

  • Ensure your Python environment is properly set up.
  • If you’re using Python 3, you might need to run:
    Terminal window
    pip3 install raise_sdk
  • If you’re working within a virtual environment, make sure it is activated before running the install command.

Usage

The main entry point of the module is exposed as start() through the revo submodule. The typical usage pattern is as follows:

from raise_sdk import revo


revo.start(
  script=[],         // List of paths to your script file(s). The main file must be named `main.py`
  requirements=[],   // List of paths to your `requirements.txt` file(s)
  dataset=[]         // List of paths to your dataset file(s)
  programming_language = "python",  // Programming language used in the experiment
  version              = "3.11",    // Specific version of the programming language
)

If any of the parameters (script, requirements, or dataset) are not provided, the module will prompt you to select the necessary files via a file selection dialog.

The module will try to connect to the Docker daemon; if it is not available, the user will be asked if he wants to run the experiment as a standard Python script (NOTE: in the latter case, the requirements will be installed in the active environment). If the experiment is run with Docker, the two optional parameters programming_language and version are used to configure the Docker image itself (and therefore the programming language the experiment will be run with); The default configuration uses “Python 3.11”.

How It Works

  1. File Selection :
    If no file paths are provided, the module uses UI dialogs to allow the user to select:

    • The processing script(s) (the main file must be named main.py)
    • The requirements.txt file
    • The dataset file(s)

  2. Local Setup and Execution :
    A LocalCodeRunner instance is created. This class:

    • Prepares an experiment directory by copying the provided files.
    • Configures the environment, including creating a Dockerfile (if Docker is available).
    • Logs the execution details.

  3. Remote Execution (Docker Integration) :
    The module checks for a Docker daemon connection.

    • If Docker is available, the experiment is executed inside a Docker container.
    • If Docker is unavailable, a prompt asks whether to proceed without Docker:
      • Proceeding runs the experiment as a standard Python script.
      • Otherwise, the execution halts with a SystemExit.

  4. Execution Logging :
    Execution time and status are logged. In particular, the LocalCodeRunner instance provides a status_code attribute that indicates the outcome of the experiment execution. The values are interpreted as follows:

    • 0 : Execution ended successfully.
    • 1 : The results folder is empty or a specific file in the results folder is empty.
    • 2 : An exception occurred while:
      • Running the Docker container,
      • Running the experiment as a standard Python script, or
      • Checking the results.

API Reference

start(script, requirements, dataset, programming_language, version)

This function, imported as start() from the revo submodule, is the primary entry point to execute an experiment.

Parameters :

  • script (list of str): A list of paths to your script files. The main file that will be executed must be named main.py.
  • requirements (list of str): A list of paths to your requirements.txt file(s).
  • dataset (list of str): A list of paths to your dataset file(s).
  • programming_language (str, optional): The programming language used in the experiment. This is used when running the experiment in a Docker container to configure the Docker image accordingly. The default is "python".
  • version (str, optional): The specific version of the programming language to be used in the experiment (when running the experiment with Docker). The default is "3.11".

Raises :

  • SystemExit :
    Raised if the Docker daemon is unavailable and the user opts not to proceed without Docker.

LocalCodeRunner

The LocalCodeRunner class is responsible for orchestrating the experiment execution. It handles file preparation, Docker image building and container execution.

Key Methods:

  • prepare_experiment_path()
    Prepares the experiment directory by copying the selected script(s), requirements, and dataset file(s). It also writes the Dockerfile when Docker is available.

  • build_docker_image()
    Builds a Docker image for the experiment if Docker is available.

  • run_docker_container()
    Executes the experiment inside a Docker container. Uses environment variables and volume bindings to manage logs and results.

  • run_python()
    Executes the experiment as a standard Python script when Docker is not available.

  • check_results()
    Validates the results of the experiment, ensuring that the output files are present and non-empty.

  • remove_image()
    Removes the Docker image created for the experiment after execution.

  • environment_variables()
    Prepares the necessary environment variables for the Docker container.