Python API
Use the factories in sen4cap_client.api. They select the Sen4CAP configuration,
saved profile, and job-result opener. The re-exported Client, AsyncClient, and
ClientConfig classes are Cuiman classes; constructing Client() directly uses
Cuiman's defaults instead.
Create a client
After configuring and logging in, you can list processes:
from contextlib import closing
from sen4cap_client.api import create_client
with closing(create_client()) as client:
processes = client.get_processes()
for process in processes.processes:
print(process.id, process.title)
The factory accepts api_url, auth, and config_path overrides. See
configuration for nested authentication settings and precedence.
Creating a client does not contact the service or prompt for credentials.
Call client.login() explicitly when interactive authentication is needed;
ordinary API calls do not prompt. Use client.login(save=True) to persist
credentials in the OS keyring for the selected profile.
Execute a process and open its result
Process IDs, input names, and output names come from the service. Inspect
client.get_process(process_id) before building a request. This example uses
the shared NDVI request for process 218. Run it from the repository root and
adapt examples/guides/ndvi-request.json to your deployment first; its input
and output keys are UUIDs from the example service, not display labels.
The Python API guide shows the request and each step.
from contextlib import closing
from pathlib import Path
from gavicore.models import ProcessRequest
from sen4cap_client.api import create_client
with closing(create_client()) as client:
request = ProcessRequest.model_validate_json(
Path("examples/guides/ndvi-request.json").read_text(encoding="utf-8")
)
job = client.execute_process(process_id="218", request=request)
print(job.jobID, job.status)
data = client.open_job_result(
job_id=job.jobID, asset_name="SNDVI", timeout=3600
)
try:
print(data)
finally:
data.close()
execute_process() submits a server-side job and returns a JobInfo; it does
not wait for processing to finish. Keep its jobID for subsequent calls.
open_job_result() polls accepted/running jobs until completion or timeout.
If results contain several outputs, pass output_name to select one.
The Sen4CAP opener requires a result link to a STAC item with
/collections/…/items/… in its URL and an asset_name option. The selected asset
must have alternate.s3.href; it is opened with rioxarray.open_rasterio().
For the single-raster NDVI example this returns an xarray.DataArray. The STAC
and raster URLs must be accessible independently: this opener does not forward
the processing API's authentication headers. Other output formats may be handled
by Cuiman's built-in openers.
Asynchronous calls
import asyncio
from sen4cap_client.api import create_async_client
async def main():
client = create_async_client()
try:
processes = await client.get_processes()
print(processes)
finally:
await client.close()
asyncio.run(main())
In a notebook use await main() instead of asyncio.run(main()). Await the
async client's API operations, login(), open_job_result(), and close().
show_app() is a regular method on either client.
Methods and errors
| Method | Purpose |
|---|---|
get_capabilities() / get_conformance() |
Inspect the service and supported standards. |
get_processes() / get_process(process_id) |
Discover processes and their input/output schemas. |
execute_process(process_id, request) |
Submit a ProcessRequest; return a JobInfo. |
get_jobs() / get_job(job_id) |
List jobs or inspect one job's status. |
get_job_results(job_id) |
Retrieve output values or links for a successful job. |
open_job_result(job_id, **options) |
Wait for completion and open a selected output. |
dismiss_job(job_id) |
Cancel a running job or delete a finished job. |
show_app() |
Open the GUI and return an app object. |
Models such as ProcessRequest, JobInfo, and JobResults are provided by
gavicore.models. Import API errors from cuiman.api, for example
from cuiman.api import ClientError; they are not exported by sen4cap_client.
Result opening can also raise JobResultOpenError, JobResultStatusError
(from cuiman.api.opener), or TimeoutError.
For the full inherited API, see Cuiman.
The Python API guide and App guide demonstrate
the workflow using the maintained examples in examples/guides/. The independent
notebooks
remain available in the repository; they are not published as documentation pages.
Sen4CAP factory reference
sen4cap_client.api.create_client(**config)
Create a synchronous Sen4CAP client from given configuration.
Uses the Sen4CAP profile, environment namespace, and result opener.
Explicit settings override environment variables and the saved profile
written by sen4cap-client configure. Authentication fields belong in
the nested auth mapping. Call login() explicitly if interactive
authentication is needed, and close() when finished.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
Any
|
Client options such as |
{}
|
Returns: An instance of a synchronous cuiman client for Sen4CAP. See https://eo-tools.github.io/eozilla/cuiman/ for details.
Source code in src\sen4cap_client\api.py
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | |
sen4cap_client.api.create_async_client(**config)
Create an asynchronous Sen4CAP client from given configuration.
Uses the same Sen4CAP settings and result opener as create_client().
Authentication fields belong in the nested auth mapping. Await service
calls, login(), and close(); client construction is synchronous.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
Any
|
Client options such as |
{}
|
Returns: An instance of an asynchronous cuiman client for Sen4CAP. See https://eo-tools.github.io/eozilla/cuiman/ for details.
Source code in src\sen4cap_client\api.py
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | |