Overview

Overview#

The VSO API Client is a Python library that simplifies interaction with the Volcano Space Observatory API. It handles authentication, job submission, status monitoring, and result retrieval for VSO workflows.

Installation#

pip install --index-url https://git.icare.univ-lille.fr/api/v4/groups/178/-/packages/pypi/simple vso-api-client

Quick Start#

Instantiate client#

import time
from uuid import uuid4

from vso_api_client import Client
from vso_api_client.exceptions import APIError, NotFoundError

# Initialise client
client = Client()

Check supported workflows#

A list of supported workflows can be obtained with the following:

workflows = client.get_workflows()

You can get examples of expected parameters for a given workflow with the following:

examples = client.get_workflow_examples(workflow=workflow_name)

Submit job#

response = client.submit_job(workflow=workflow_name, job_parameters=your_parameters)

Alternatively, you can provide the path to a json file containing the job parameters:

response = client.submit_job(
    workflow=workflow_name, job_parameters="path/to/job_params.json"
)

On the first call, you will be prompted to log in in your browser to obtain an access token. Further requests will then use the token and automatically refresh it if necessary. However, if you already have a valid access token that can be used to authenticate to the VSO API, you can provide it as a keyword argument when submitting your job:

response = client.submit_job(
    workflow=workflow_name,
    job_parameters=your_parameters,
    access_token=your_access_token
)

Monitoring job progress and get results#

job_id = response["job_id"]

# Wait for completion
while not client.get_has_job_ended(job_id)["has_ended"]:
    time.sleep(5)
    try:
        progress = client.get_job_progress(job_id)["progress"]
    except APIError as e:
        if isinstance(e, NotFoundError) and e.message == "Progress artifact not found":
            print("Job has not started yet")
            continue
        else:
            raise e
    print(f"Progress: {progress}%")

status = client.get_job_status(job_id)["status"]
if status != "COMPLETED":
    raise Exception(
        f"Job failed with status: {status}, you may contact us for support.")

print("Job completed!")
# Download results as json dict
result = client.get_job_result(job_id)

Cancel job#

You can cancel a job you have submitted as follows:

client.cancel_job(job_id)

As with submission, you can provide an access token as a keyword argument:

client.cancel_job(job_id, access_token=your_access_token)

Licence#

This project is licensed under the GNU Affero General Public License v3.0.

Acknowledgements#

  • CNES (Centre National d’Études Spatiales)

  • CNRS (Centre National de la Recherche Scientifique)

  • Université de Lille

  • Région Hauts-de-France

Contents