Python API usage¶

The Python API client allows for

client.get_processes(): listing existing processes,
client.get_process(): get the details about a process,
client.execute_process(): executing a given process execution request,
client.get_jobs(): observing the jobs resulting from a process execution,
client.get_job(): getting a job's details,
client.get_job_result(): getting a job's result, and finally
client.dismiss_job(): cancelling a job.

In the following, we visit all the features by example.

The client expects a running server that conforms to the OGC API - Process: Part 1, Version 1.0. If you don't have one available, you can also run the project's server with a test configuration:

wraptile run -- wraptile.services.local.testing:service

In [1]:

Copied!

from cuiman import Client
from gavicore.models import ProcessRequest
from cuiman import Client
from gavicore.models import ProcessRequest

In [2]:

Copied!

client = Client()
client
client = Client()
client

Out[2]:

{
  "access_token": "1234",
  "server_url": "http://127.0.0.1:8008",
  "user_name": "bibo"
}

In [3]:

Copied!

client.get_capabilities()
client.get_capabilities()

Out[3]:

{
  "description": "Local test server implementing the OGC API - Processes 1.0 Standard",
  "links": [
    {
      "href": "http://127.0.0.1:8008/",
      "hreflang": "en",
      "rel": "self",
      "title": "get_capabilities",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/openapi.json",
      "hreflang": "en",
      "rel": "service",
      "title": "openapi",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/docs",
      "hreflang": "en",
      "rel": "service",
      "title": "swagger_ui_html",
      "type": "text/html"
    },
    {
      "href": "http://127.0.0.1:8008/docs/oauth2-redirect",
      "hreflang": "en",
      "rel": "service",
      "title": "swagger_ui_redirect",
      "type": "text/html"
    },
    {
      "href": "http://127.0.0.1:8008/redoc",
      "hreflang": "en",
      "rel": "service",
      "title": "redoc_html",
      "type": "text/html"
    },
    {
      "href": "http://127.0.0.1:8008/",
      "hreflang": "en",
      "rel": "service",
      "title": "get_capabilities",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/conformance",
      "hreflang": "en",
      "rel": "service",
      "title": "get_conformance",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/processes",
      "hreflang": "en",
      "rel": "service",
      "title": "get_processes",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/processes/{processID}",
      "hreflang": "en",
      "rel": "service",
      "title": "get_process",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/processes/{processID}/execution",
      "hreflang": "en",
      "rel": "service",
      "title": "execute_process",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/jobs",
      "hreflang": "en",
      "rel": "service",
      "title": "get_jobs",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/jobs/{jobId}",
      "hreflang": "en",
      "rel": "service",
      "title": "get_job",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/jobs/{jobId}",
      "hreflang": "en",
      "rel": "service",
      "title": "dismiss_job",
      "type": "application/json"
    },
    {
      "href": "http://127.0.0.1:8008/jobs/{jobId}/results",
      "hreflang": "en",
      "rel": "service",
      "title": "get_job_results",
      "type": "application/json"
    }
  ],
  "title": "S2GOS API Server (local dummy for testing)"
}

In [4]:

Copied!

client.get_conformance()
client.get_conformance()

Out[4]:

{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/ogc-process-description",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/json",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/oas30",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/job-list",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/dismiss"
  ]
}

In [5]:

Copied!

client.get_processes()
client.get_processes()

Out[5]:

{
  "links": [
    {
      "href": "http://127.0.0.1:8008/processes",
      "hreflang": "en",
      "rel": "self",
      "title": "get_processes",
      "type": "application/json"
    }
  ],
  "processes": [
    {
      "description": "Sleeps for `duration` seconds. Fails on purpose if `fail` is `True`. Returns the effective amount of sleep in seconds.",
      "id": "sleep_a_while",
      "title": "Sleep Processor",
      "version": "0.0.0"
    },
    {
      "description": "Returns the list of prime numbers between a `min_val` and `max_val`.",
      "id": "primes_between",
      "title": "Prime Processor",
      "version": "0.0.0"
    },
    {
      "description": "Simulate a set scene images slices for testing. Creates an xarray dataset with `periodicity` time slices and writes it as Zarr into a temporary location. Requires installed `dask`, `xarray`, and `zarr` packages.",
      "id": "simulate_scene",
      "title": "Generate scene for testing",
      "version": "0.0.0"
    },
    {
      "id": "return_base_model",
      "title": "BaseModel Test",
      "version": "0.0.0"
    }
  ]
}

In [6]:

Copied!

client.get_process(process_id="sleep_a_while")
client.get_process(process_id="sleep_a_while")

Out[6]:

{
  "description": "Sleeps for `duration` seconds. Fails on purpose if `fail` is `True`. Returns the effective amount of sleep in seconds.",
  "id": "sleep_a_while",
  "inputs": {
    "duration": {
      "minOccurs": 0,
      "schema": {
        "default": 10,
        "type": "number"
      },
      "title": "Duration"
    },
    "fail": {
      "minOccurs": 0,
      "schema": {
        "default": false,
        "type": "boolean"
      },
      "title": "Fail"
    }
  },
  "outputs": {
    "return_value": {
      "schema": {
        "type": "number"
      },
      "title": "Return Value"
    }
  },
  "title": "Sleep Processor",
  "version": "0.0.0"
}

In [7]:

Copied!

client.get_jobs()
client.get_jobs()

Out[7]:

{
  "jobs": [],
  "links": [
    {
      "href": "http://127.0.0.1:8008/jobs",
      "hreflang": "en",
      "rel": "self",
      "title": "get_jobs",
      "type": "application/json"
    }
  ]
}

In [8]:

Copied!

client.execute_process(process_id="sleep_a_while", request=ProcessRequest(duration=2))
client.execute_process(process_id="sleep_a_while", request=ProcessRequest(duration=2))

Out[8]:

{
  "created": "2025-10-07T14:27:18.702704Z",
  "jobID": "job_0",
  "processID": "sleep_a_while",
  "progress": 0,
  "started": "2025-10-07T14:27:18.703480Z",
  "status": "running",
  "type": "process",
  "updated": "2025-10-07T14:27:18.703722Z"
}

In [9]:

Copied!

client.execute_process(process_id="sleep_a_while", request={"fail": True})
client.execute_process(process_id="sleep_a_while", request={"fail": True})

Out[9]:

{
  "created": "2025-10-07T14:27:18.729307Z",
  "jobID": "job_1",
  "processID": "sleep_a_while",
  "progress": 0,
  "started": "2025-10-07T14:27:18.730120Z",
  "status": "running",
  "type": "process",
  "updated": "2025-10-07T14:27:18.730187Z"
}

In [10]:

Copied!

client.execute_process(process_id="primes_between", request={})
client.execute_process(process_id="primes_between", request={})

Out[10]:

{
  "created": "2025-10-07T14:27:18.752928Z",
  "finished": "2025-10-07T14:27:18.753685Z",
  "jobID": "job_2",
  "message": "Done",
  "processID": "primes_between",
  "started": "2025-10-07T14:27:18.753482Z",
  "status": "successful",
  "type": "process",
  "updated": "2025-10-07T14:27:18.753659Z"
}

In [11]:

Copied!

client.get_jobs()
client.get_jobs()

Out[11]:

{
  "jobs": [
    {
      "created": "2025-10-07T14:27:18.702704Z",
      "jobID": "job_0",
      "processID": "sleep_a_while",
      "progress": 0,
      "started": "2025-10-07T14:27:18.703480Z",
      "status": "running",
      "type": "process",
      "updated": "2025-10-07T14:27:18.703722Z"
    },
    {
      "created": "2025-10-07T14:27:18.729307Z",
      "jobID": "job_1",
      "processID": "sleep_a_while",
      "progress": 0,
      "started": "2025-10-07T14:27:18.730120Z",
      "status": "running",
      "type": "process",
      "updated": "2025-10-07T14:27:18.730187Z"
    },
    {
      "created": "2025-10-07T14:27:18.752928Z",
      "finished": "2025-10-07T14:27:18.753685Z",
      "jobID": "job_2",
      "message": "Done",
      "processID": "primes_between",
      "started": "2025-10-07T14:27:18.753482Z",
      "status": "successful",
      "type": "process",
      "updated": "2025-10-07T14:27:18.753659Z"
    }
  ],
  "links": [
    {
      "href": "http://127.0.0.1:8008/jobs",
      "hreflang": "en",
      "rel": "self",
      "title": "get_jobs",
      "type": "application/json"
    }
  ]
}

In [12]:

Copied!

client.get_job("job_2")
client.get_job("job_2")

Out[12]:

{
  "created": "2025-10-07T14:27:18.752928Z",
  "finished": "2025-10-07T14:27:18.753685Z",
  "jobID": "job_2",
  "message": "Done",
  "processID": "primes_between",
  "started": "2025-10-07T14:27:18.753482Z",
  "status": "successful",
  "type": "process",
  "updated": "2025-10-07T14:27:18.753659Z"
}

In [13]:

Copied!

# client.get_job_results("job_1")
# client.get_job_results("job_1")

In [14]:

Copied!

for job in client.get_jobs().jobs:
    client.dismiss_job(job.jobID)
for job in client.get_jobs().jobs:
    client.dismiss_job(job.jobID)

In [15]:

Copied!

client.get_jobs()
client.get_jobs()

Out[15]:

{
  "jobs": [
    {
      "created": "2025-10-07T14:27:18.702704Z",
      "jobID": "job_0",
      "processID": "sleep_a_while",
      "progress": 1,
      "started": "2025-10-07T14:27:18.703480Z",
      "status": "running",
      "type": "process",
      "updated": "2025-10-07T14:27:18.804430Z"
    },
    {
      "created": "2025-10-07T14:27:18.729307Z",
      "jobID": "job_1",
      "processID": "sleep_a_while",
      "progress": 1,
      "started": "2025-10-07T14:27:18.730120Z",
      "status": "running",
      "type": "process",
      "updated": "2025-10-07T14:27:18.830338Z"
    }
  ],
  "links": [
    {
      "href": "http://127.0.0.1:8008/jobs",
      "hreflang": "en",
      "rel": "self",
      "title": "get_jobs",
      "type": "application/json"
    }
  ]
}

In [ ]: