Cuiman API Reference

The Cuiman Python API is provided by the cuiman package.

The Client class provides a synchronous API. If you want an asynchronous version, use the AsyncClient class instead. It provides the same interface, but using asynchronous server calls.

Both clients return their configuration as a ClientConfig object.

Methods of the Client and AsyncClient may raise a ClientError if a server call fails.

cuiman.Client

Client(
    *,
    config: Optional[ClientConfig] = None,
    config_path: Optional[str] = None,
    api_url: Optional[str] = None,
    _debug: bool = False,
    _transport: Optional[Transport] = None,
    **config_kwargs: Any
)

Bases: ClientMixin

The client API for the web service (synchronous mode).

Parameters:

Name	Type	Description	Default
`config`	`Optional[ClientConfig]`	Optional client configuration object. If given, other configuration arguments are ignored.	`None`
`config_path`	`Optional[str]`	Optional path of the configuration file to be loaded	`None`
`api_url`	`Optional[str]`	The service URL of the OGC API - Processes.	`None`
`config_kwargs`	`Any`	Configuration settings as keyword arguments.	`{}`

create_execution_request

create_execution_request(
    process_id: str, dotpath: bool = False
) -> ExecutionRequest

Create a template for an execution request generated from the process description of the given process identifier.

Parameters:

Name	Type	Description	Default
`process_id`	`str`	The process identifier	required
`dotpath`	`bool`	Whether to create dot-separated input names for nested object values	`False`

Returns:

Type	Description
`ExecutionRequest`	The execution request template.

Raises:

Type	Description
`ClientError`	if an API error occurs

open_job_result

open_job_result(
    job_id: str,
    output_name: str | None = None,
    data_type: type | None = None,
    media_type: str | None = None,
    poll_interval: float = DEFAULT_OPEN_JOB_JOB_POLL_INTERVAL,
    timeout: float = DEFAULT_OPEN_JOB_RESULT_TIMEOUT,
    **options: Any
) -> Any

Open the results of the job given by its ID.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	the job ID	required
`output_name`	`str \| None`	the name of the output to be opened.	`None`
`data_type`	`type \| None`	the expected/desired data type to be returned. If provided, the return value will be of that type. If not provided, the return value will be the type decided by the opener.	`None`
`media_type`	`str \| None`	the media type of the output produced. Only needed, if the output does not provide its media type or if its media type should be overridden.	`None`
`poll_interval`	`float`	interval in seconds between job status polls. Applies while job status is still "accepted" or "running".	`DEFAULT_OPEN_JOB_JOB_POLL_INTERVAL`
`timeout`	`float`	maximum time in seconds to wait for job completion.	`DEFAULT_OPEN_JOB_RESULT_TIMEOUT`
`options`	`Any`	additional opener-specific options.	`{}`

Returns:

Type	Description
`Any`	The job result value.

Raises:

Type	Description
`ClientError`	if an API error occurs
`JobResultOpenError`	if an opener error occurs
`JobResultStatusError`	if the job failed or was canceled
`TimeoutError`	if the job does not finish within the timeout

get_capabilities

get_capabilities(**kwargs: Any) -> Capabilities

The landing page provides links to the

The OpenAPI-definition (no fixed path),
The Conformance statements (path /conformance),
The processes metadata (path /processes),
The endpoint for job monitoring (path /jobs).

For more information, see OGC API — Processes — Part 1 Section 7.2.

Returns:

Name	Type	Description
`Capabilities`	`Capabilities`	The landing page provides links to the API definition (link relations `service-desc` and `service-doc`), the Conformance declaration (path `/conformance`, link relation `http://www.opengis.net/def/rel/ogc/1.0/conformance`), and to other resources.

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`. `500`: A server error occurred.

get_conformance

get_conformance(**kwargs: Any) -> ConformanceDeclaration

A list of all conformance classes, specified in a standard, that the server conforms to.

Conformance class	URI
Core	http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core
OGC Process Description	http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/ogc-process-description
JSON	http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/json
HTML	http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/html
OpenAPI Specification 3.0	http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/oas30
Job list	http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/job-list
Callback	http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/callback
Dismiss	http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/dismiss

For more information, see OGC API — Processes — Part 1 Section 7.4.

Returns:

Name	Type	Description
`ConformanceDeclaration`	`ConformanceDeclaration`	The URIs of all conformance classes supported by the server. To support "generic" clients that want to access multiple OGC API - Processes implementations - and not "just" a specific API / server, the server declares the conformance classes it implements and conforms to.

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`. `500`: A server error occurred.

get_processes

get_processes(**kwargs: Any) -> ProcessList

The list of processes contains a summary of each process the OGC API - Processes offers, including the link to a more detailed description of the process.

For more information, see OGC API — Processes — Part 1 Section 7.9.

Returns:

Name	Type	Description
`ProcessList`	`ProcessList`	Information about the available processes

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`.

get_process

get_process(process_id: str, **kwargs: Any) -> ProcessDescription

The process description contains information about inputs and outputs and a link to the execution-endpoint for the process. The Core does not mandate the use of a specific process description to specify the interface of a process. That said, the Core requirements class makes the following recommendation:

Implementations should consider supporting the OGC process description.

For more information, see OGC API — Processes — Part 1 Section 7.10.

Parameters:

Name	Type	Description	Default
`process_id`	`str`		required
`kwargs`	`Any`	Optional keyword arguments that may be used by the underlying transport.	`{}`

Returns:

Name	Type	Description
`ProcessDescription`	`ProcessDescription`	A process description.

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`. `404`: The requested URI was not found.

execute_process

execute_process(
    process_id: str, request: ProcessRequest, **kwargs: Any
) -> JobInfo

Create a new job.

For more information, see OGC API — Processes — Part 1 Section 7.11.

Parameters:

Name	Type	Description	Default
`process_id`	`str`		required
`kwargs`	`Any`	Optional keyword arguments that may be used by the underlying transport.	`{}`
`request`	`ProcessRequest`	Mandatory request JSON	required

Returns:

Name	Type	Description
`JobInfo`	`JobInfo`	Started asynchronous execution. Created job.

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`. `404`: The requested URI was not found. `500`: A server error occurred.

get_jobs

get_jobs(**kwargs: Any) -> JobList

List available jobs.

For more information, see OGC API — Processes — Part 1 Section 11.

Returns:

Name	Type	Description
`JobList`	`JobList`	A list of jobs for this process.

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`. `404`: The requested URI was not found.

get_job

get_job(job_id: str, **kwargs: Any) -> JobInfo

Show the status of a job.

For more information, see OGC API — Processes — Part 1 Section 7.12.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	Local identifier of a job	required
`kwargs`	`Any`	Optional keyword arguments that may be used by the underlying transport.	`{}`

Returns:

Name	Type	Description
`JobInfo`	`JobInfo`	The status of a job.

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`. `404`: The requested URI was not found. `500`: A server error occurred.

dismiss_job

dismiss_job(job_id: str, **kwargs: Any) -> JobInfo

Cancel a job execution and removes it from the jobs list.

For more information, see OGC API — Processes — Part 1 Section 13.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	Local identifier of a job	required
`kwargs`	`Any`	Optional keyword arguments that may be used by the underlying transport.	`{}`

Returns:

Name	Type	Description
`JobInfo`	`JobInfo`	Information about the job.

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`. `404`: The requested URI was not found. `500`: A server error occurred.

get_job_results

get_job_results(job_id: str, **kwargs: Any) -> JobResults

List available results of a job. In case of a failure, list errors instead.

For more information, see OGC API — Processes — Part 1 Section 7.13.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	Local identifier of a job	required
`kwargs`	`Any`	Optional keyword arguments that may be used by the underlying transport.	`{}`

Returns:

Name	Type	Description
`JobResults`	`JobResults`	The results of a job.

Raises:

Type	Description
`ClientError`	If the call to the web service fails with a status code != `2xx`. `404`: The requested URI was not found. `500`: A server error occurred.

close

close()

Close this client.

cuiman.ClientConfig

Bases: AuthConfig, BaseSettings

Client configuration.

Parameters:

Name	Type	Description	Default
`api_url`		a URL pointing to a service compliant with the OCG API - Processes.	required

auth_headers `property`

auth_headers: dict[str, str]

Return the HTTP authentication headers for this auth configuration.

default_config `class-attribute`

default_config: ClientConfig

Default instance. Used to create pre-configured instances of this class. Designed to be overridden by library clients.

default_path `class-attribute`

default_path: Path

Name of the configuration's local default path. Used for configuration persistence in ~/.<config_name>/. Designed to be overridden by library clients.

return_type_map `class-attribute`

return_type_map: dict[type, type] = {}

A mapping from a hard-coded client return type to a custom return type. The hard-coded return type is usually a model class from gavicore.models. The custom return type typically extends the model class.
Designed to be configured by library clients. The default mapping is empty.

api_url `class-attribute` `instance-attribute`

api_url: Annotated[Optional[str], Field(title='Process API URL')] = None

The URL of the server that provides a web API compliant with OGC API - Processes, Part 1 - Core.

accept_process `classmethod`

accept_process(process_summary: ProcessSummary, **filter_kwargs: Any) -> bool

Predicate function that is used to filter the list of processes. The function is intended to be overridden by subclasses in order to allow for evaluating the given process_summary in an application-specific way. This includes the using custom fields in the given ProcessSummary instance.

Applications may use the extend_model() function to enhance existing model classes by their custom fields.

The default implementation unconditionally returns True.

Parameters:

Name	Type	Description	Default
`process_summary`	`ProcessSummary`	A process summary.	required
`filter_kwargs`	`Any`	Implementation specific arguments passed by a user of this class.	`{}`

Returns:

Type	Description
`bool`	`True` to accept the given process, otherwise `False`.

accept_input `classmethod`

accept_input(
    process_description: ProcessDescription,
    input_name: str,
    input_description: InputDescription,
    **filter_kwargs: Any
) -> bool

Predicate function that is used to filter the list of inputs of a process. The function is intended to be overridden by subclasses in order to allow for evaluating the given input_description in an application-specific way. This includes the using custom fields in the given InputDescription instance.

Applications may use the extend_model() function to enhance existing model classes by their custom fields.

The default implementation unconditionally returns True.

Parameters:

Name	Type	Description	Default
`process_description`	`ProcessDescription`	The process description.	required
`input_name`	`str`	The input's name.	required
`input_description`	`InputDescription`	A description of an input of the given `process_description`.	required
`filter_kwargs`	`Any`	Implementation specific arguments passed by a user of this class.	`{}`

Returns:

Type	Description
`bool`	`True` to accept the given input, otherwise `False`.

is_advanced_input `classmethod`

is_advanced_input(
    process_description: ProcessDescription,
    input_name: str,
    input_description: InputDescription,
) -> bool

Experimental method, do not use!

Designed to be overridden by a custom ClientConfig class from which an instance will be assigned to ClientConfig.default_config to become effective.

The default implementations checks if the given input_description has additionalParameters, and if so, if a parameter with name "level" has value ["advanced"] (a list!).

Parameters:

Name	Type	Description	Default
`process_description`	`ProcessDescription`	The process description.	required
`input_name`	`str`	The input's name.	required
`input_description`	`InputDescription`	A description of an input of the given `process_description`.	required

Returns:

Type	Description
`bool`	`True` if the input is advanced
`bool`	(e.g. for advanced process users only).

register_job_result_opener `classmethod`

register_job_result_opener(
    opener_type: type[JobResultOpener],
) -> Callable[[], None]

Register a job result opener.

Parameters:

Name	Type	Description	Default
`opener_type`	`type[JobResultOpener]`	The type of the opener to be registered.	required

Returns:

Type	Description
`Callable[[], None]`	A function that can be called to unregister the opener.

get_job_result_opener_registry `cached` `classmethod`

get_job_result_opener_registry() -> JobResultOpenerRegistry

Get the registry for openers that are used to open job results.

Use it to register custom openers for special job results.

Note that the registry contains types/classes, not instances.

get_field_factory_registry `cached` `classmethod`

get_field_factory_registry() -> FieldFactoryRegistry

Get the registry for factories that generate UI fields from process inputs.

Used in the GUI client cuiman.gui.Client. Use it to register factories that customize the way the client GUI is generated.

The default registry contains factories that creates UI fields for the Panel library as this is the primary library used in the GUI client.

The default registry type is gavicore.ui.panel.PanelFieldFactoryRegistry.

The type of registered field factories is gavicore.ui.panel.PanelFieldFactory.

The type of the field instances created by the factories must be gavicore.ui.panel.PanelField.

cuiman.ClientError

ClientError(message: str, api_error: ApiError)

Bases: Exception

Raised if a web API call failed.

The failure can have several reasons such as

the request failed with a status code that is not 2xx, or
the received JSON response is not parsable.

Parameters:

Name	Type	Description	Default
`message`	`str`	The error message	required
`api_error`	`ApiError`	The details describing the error that occurred on the server or the details that describe a non-expected response from the server.	required

Cuiman API Reference

cuiman.Client

create_execution_request

open_job_result

get_capabilities

get_conformance

get_processes

get_process

execute_process

get_jobs

get_job

dismiss_job

get_job_results

close

cuiman.ClientConfig

auth_headers property

default_config class-attribute

default_path class-attribute

return_type_map class-attribute

api_url class-attribute instance-attribute

accept_process classmethod

accept_input classmethod

is_advanced_input classmethod

register_job_result_opener classmethod

get_job_result_opener_registry cached classmethod

get_field_factory_registry cached classmethod

cuiman.ClientError

auth_headers `property`

default_config `class-attribute`

default_path `class-attribute`

return_type_map `class-attribute`

api_url `class-attribute` `instance-attribute`

accept_process `classmethod`

accept_input `classmethod`

is_advanced_input `classmethod`

register_job_result_opener `classmethod`

get_job_result_opener_registry `cached` `classmethod`

get_field_factory_registry `cached` `classmethod`