Cuiman Python API usage¶

The Cuiman 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]:

{
  "api_key": null,
  "api_key_header": "X-API-Key",
  "api_url": "http://127.0.0.1:8008/",
  "auth_type": "basic",
  "auth_url": null,
  "password": "gfds",
  "token": null,
  "token_header": "X-Auth-Token",
  "use_bearer": false,
  "username": "Norman"
}

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": "Eozilla 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"
    },
    {
      "description": "This is a workflow with several steps and defined dependencies that execute sequentially.",
      "id": "process_pipeline",
      "title": "A Big Workflow",
      "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(inputs={"duration":2}))
client.execute_process(process_id="sleep_a_while", request=ProcessRequest(inputs={"duration":2}))

Out[8]:

{
  "created": "2026-02-12T16:13:30.682487Z",
  "jobID": "job_0",
  "processID": "sleep_a_while",
  "progress": 0,
  "started": "2026-02-12T16:13:30.683002Z",
  "status": "running",
  "type": "process",
  "updated": "2026-02-12T16:13:30.683152Z"
}

In [9]:

Copied!

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

Out[9]:

{
  "created": "2026-02-12T16:13:30.693029Z",
  "jobID": "job_1",
  "processID": "sleep_a_while",
  "progress": 0,
  "started": "2026-02-12T16:13:30.693375Z",
  "status": "running",
  "type": "process",
  "updated": "2026-02-12T16:13:30.693446Z"
}

In [10]:

Copied!

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

Out[10]:

{
  "created": "2026-02-12T16:13:30.702482Z",
  "finished": "2026-02-12T16:13:30.703101Z",
  "jobID": "job_2",
  "message": "Done",
  "processID": "primes_between",
  "started": "2026-02-12T16:13:30.702895Z",
  "status": "successful",
  "type": "process",
  "updated": "2026-02-12T16:13:30.703050Z"
}

In [11]:

Copied!

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

Out[11]:

{
  "description": "This is a workflow with several steps and defined dependencies that execute sequentially.",
  "id": "process_pipeline",
  "inputs": {
    "id": {
      "schema": {
        "type": "string"
      },
      "title": "main input"
    }
  },
  "outputs": {
    "final": {
      "schema": {
        "items": {
          "items": {
            "type": "string"
          },
          "maxItems": 2,
          "minItems": 2,
          "type": "array"
        },
        "maxItems": 2,
        "minItems": 2,
        "type": "array"
      },
      "title": "Final output"
    }
  },
  "title": "A Big Workflow",
  "version": "0.0.0"
}

In [12]:

Copied!

client.execute_process(process_id="process_pipeline", request=ProcessRequest(inputs={"id": "eozilla-is-wow"}))
client.execute_process(process_id="process_pipeline", request=ProcessRequest(inputs={"id": "eozilla-is-wow"}))

Out[12]:

{
  "created": "2026-02-12T16:13:30.722516Z",
  "jobID": "job_3",
  "processID": "process_pipeline",
  "status": "accepted",
  "type": "process"
}

In [13]:

Copied!

client.get_jobs()
client.get_jobs()

Out[13]:

{
  "jobs": [
    {
      "created": "2026-02-12T16:13:30.682487Z",
      "jobID": "job_0",
      "processID": "sleep_a_while",
      "progress": 2,
      "started": "2026-02-12T16:13:30.683002Z",
      "status": "running",
      "type": "process",
      "updated": "2026-02-12T16:13:30.724402Z"
    },
    {
      "created": "2026-02-12T16:13:30.693029Z",
      "jobID": "job_1",
      "processID": "sleep_a_while",
      "progress": 0,
      "started": "2026-02-12T16:13:30.693375Z",
      "status": "running",
      "type": "process",
      "updated": "2026-02-12T16:13:30.693446Z"
    },
    {
      "created": "2026-02-12T16:13:30.702482Z",
      "finished": "2026-02-12T16:13:30.703101Z",
      "jobID": "job_2",
      "message": "Done",
      "processID": "primes_between",
      "started": "2026-02-12T16:13:30.702895Z",
      "status": "successful",
      "type": "process",
      "updated": "2026-02-12T16:13:30.703050Z"
    },
    {
      "created": "2026-02-12T16:13:30.722516Z",
      "finished": "2026-02-12T16:13:30.723774Z",
      "jobID": "job_3",
      "processID": "process_pipeline",
      "started": "2026-02-12T16:13:30.722979Z",
      "status": "successful",
      "type": "process"
    }
  ],
  "links": [
    {
      "href": "http://127.0.0.1:8008/jobs",
      "hreflang": "en",
      "rel": "self",
      "title": "get_jobs",
      "type": "application/json"
    }
  ]
}

In [14]:

Copied!

client.get_job("job_1")
client.get_job("job_1")

Out[14]:

{
  "created": "2026-02-12T16:13:30.693029Z",
  "jobID": "job_1",
  "processID": "sleep_a_while",
  "progress": 0,
  "started": "2026-02-12T16:13:30.693375Z",
  "status": "running",
  "type": "process",
  "updated": "2026-02-12T16:13:30.693446Z"
}

In [15]:

Copied!

client.get_job_results("job_3")
client.get_job_results("job_3")

Out[15]:

{
  "final": [
    [
      "eozilla-is-wow_read_preprocessed_feature_mean",
      "resampled_from=eozilla-is-wow"
    ],
    "eozilla-is-wow_read_preprocessed_feature_mean"
  ]
}

In [16]:

Copied!

client.get_job_results("job_2")
client.get_job_results("job_2")

Out[16]:

{
  "return_value": [
    2,
    3,
    5,
    7,
    11,
    13,
    17,
    19,
    23,
    29,
    31,
    37,
    41,
    43,
    47,
    53,
    59,
    61,
    67,
    71,
    73,
    79,
    83,
    89,
    97
  ]
}

In [17]:

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 [18]:

Copied!

client.get_jobs()
client.get_jobs()

Out[18]:

{
  "jobs": [
    {
      "created": "2026-02-12T16:13:30.682487Z",
      "jobID": "job_0",
      "processID": "sleep_a_while",
      "progress": 4,
      "started": "2026-02-12T16:13:30.683002Z",
      "status": "running",
      "type": "process",
      "updated": "2026-02-12T16:13:30.765438Z"
    },
    {
      "created": "2026-02-12T16:13:30.693029Z",
      "jobID": "job_1",
      "processID": "sleep_a_while",
      "progress": 0,
      "started": "2026-02-12T16:13:30.693375Z",
      "status": "running",
      "type": "process",
      "updated": "2026-02-12T16:13:30.693446Z"
    }
  ],
  "links": [
    {
      "href": "http://127.0.0.1:8008/jobs",
      "hreflang": "en",
      "rel": "self",
      "title": "get_jobs",
      "type": "application/json"
    }
  ]
}