Cuiman API Reference

The Cuiman Python API is provided by the cuiman.api package. Frequently used classes and functions are also made available directly through the cuiman package.

Client API

Client provides the synchronous processing API; AsyncClient provides the same interface with asynchronous server calls. Server calls may raise ClientError if they fail.

For concepts and first requests, see Getting Started. See Configuration for settings and Authentication for login, token storage, and client lifecycle.

cuiman.api.Client

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

Bases: ClientAppMixin, ClientMixin

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

Parameters:

Name	Type	Description	Default
`config`	`Optional[ClientConfig]`	Optional configuration object. Explicit keyword settings override its values.	`None`
`config_type`	`type[ClientConfig] \| None`	Optional application configuration class. It owns the settings schema, defaults, environment namespace, and profile path. When omitted, a supplied `config` object's concrete type is used.	`None`
`config_path`	`Optional[str]`	Optional path of the configuration file to be loaded	`None`
`config_kwargs`	`Any`	Configuration overrides, including `auth`. An auth model or a dictionary containing `auth_type` replaces previous auth settings, even when the type is unchanged. A dictionary without `auth_type` merges into the selected auth configuration, including nested mappings. If credentials are still missing, a matching profile's keyring entry may supply them; explicitly supplied credentials take precedence.	`{}`
`api_url`	`Optional[str]`	The service URL of the OGC API - Processes.	`None`

token `property`

token: dict[str, Any] | None

Return an independent snapshot of the live OAuth token, without login.

close

close() -> None

Close owned connections. A closed client cannot be used again.

login(
    *,
    interactive: bool = True,
    no_browser: bool = False,
    force: bool = False,
    save: bool = False,
) -> None

Prepare authentication using the client's persistent HTTP session.

Use force to acquire a fresh token. Requests never prompt or open a browser. With save=True, failure to save credentials raises an error.

logout

logout() -> None

Revoke an OIDC token when supported, remove local secrets, and close.

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

show_app

show_app(
    *,
    compact: bool | None = None,
    debug: bool = False,
    scheme: Literal["dark", "light", "auto"] = "auto",
    width: int | str = "100%",
    height: int | str = 600,
    display: Literal["browser", "notebook", "auto"] = "auto",
    proxy: ProxyMode = "auto",
) -> App

Start the Cuiman app server and open the Eozilla App.

The app connects to this client's API configuration, renders the app GUI, and returns an object that provides the serve result and a shared App state, which you can interact with.

The app state currently only manages the process requests being edited and executed by a user. The requests are a mapping from process IDs to process requests.

Display the app and get the app instance:

app = client.show_app()

You can get and set process requests using the methods

app.get_process_request(process_id)
app.set_process_request(process_id, process_request)

where process_id is the process ID and process_request is a dict or a ProcessRequest object that comprises basically two attributes:

inputs: a mapping from input name to an input's value.
outputs: the outputs to be generated. Just used to detect whether an output is included or now.

Another convenient way to work with the nested app state is the process_requests property:

app.process_requests.my_process.inputs.threshold = 0.75
app.process_requests.my_process = {"inputs": {...}}

Launch process details:

The initial browser URL contains only a short-lived, single-use launch code. The app exchanges it for an HttpOnly same-origin session cookie, then replaces it with the non-sensitive cuiman=1 reload marker. It derives its service proxy and RemoteState WebSocket URLs from the browser-visible app URL, so the same flow works through a Jupyter Server Proxy path prefix without exposing the configured service URL or credentials to the browser.

Parameters:

Name	Type	Description	Default
`compact`	`bool \| None`	Compact mode. Defaults to True, if `display` is "notebook".	`None`
`debug`	`bool`	Enable app debug mode.	`False`
`scheme`	`Literal['dark', 'light', 'auto']`	Color scheme to use in the app. `"auto"` follows the surrounding notebook theme when the app is embedded.	`'auto'`
`width`	`int \| str`	Width of the notebook iframe.	`'100%'`
`height`	`int \| str`	Height of the notebook iframe.	`600`
`display`	`Literal['browser', 'notebook', 'auto']`	Where to show the app. `"auto"` embeds it in notebooks and opens it in a browser otherwise.	`'auto'`
`proxy`	`ProxyMode`	Whether notebook traffic uses `jupyter-server-proxy`. `"auto"` uses it when available, `"never"` disables it, and `"always"` requires it.	`'auto'`

Return: An App instance.

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.

cuiman.api.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

Configuration API

cuiman.api.ClientConfig

Bases: BaseSettings

Client configuration.

Attributes:

Name	Type	Description
`api_url`	`Annotated[Optional[str], Field(title='Process API URL')]`	a URL pointing to a service compliant with the OGC API - Processes.

default_path `class-attribute`

default_path: Path = Path('~').expanduser() / '.eozilla' / 'config'

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

display_name `class-attribute`

display_name: str | None = None

Application name for notebook labels and app-launch errors.

Override in an application subclass. When absent, messages use neutral wording. This metadata is excluded from settings and saved profiles.

cli_name `class-attribute`

cli_name: str | None = None

Optional command name for login guidance in the Python API.

Set only when the application provides a CLI. CLI instances use their own new_cli(name=...) value instead. This metadata is not persisted.

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.

extra_job_result_openers `class-attribute`

extra_job_result_openers: Iterable[type[JobResultOpener]] = ()

Additional job result opener classes for this application.

Declare an iterable in a subclass. It is captured as a tuple at class creation so generators can be inherited safely. Openers are registered after the built-ins, in iteration order, so the last entry is tried first. Each class's registry is initialized on first use; later changes should use register_job_result_opener(). This class attribute is excluded from configuration settings and persistence.

api_url `class-attribute` `instance-attribute`

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

The URL of the server that provides a web API compliant with OGC API - Processes, Part 1 - Core. Validated with HttpUrl but stored as a string for consumers that join paths using string operations; an empty string or None means unconfigured.

This is a base URL: Python and app requests append endpoint paths with one slash separator. Both /process and /process/ therefore use /process/ for the landing page and /process/processes for the process list. This joining rule belongs to request construction, not validation: HttpUrl preserves a non-empty path's trailing slash and adds / to a bare host. Authentication endpoint paths instead retain their configured trailing slash when making requests.

auth `class-attribute` `instance-attribute`

auth: AuthConfig = Field(default_factory=NoAuthConfig)

Authentication configuration selected by its auth_type field.

When resolving settings with create(), an auth model or a dictionary containing auth_type replaces previous auth settings. A dictionary without auth_type merges into the selected configuration. Matching keyring credentials may fill missing secrets after resolution.

create `classmethod`

create(
    *,
    config: Optional[ClientConfig] = None,
    config_type: type[ClientConfig] | None = None,
    config_path: Optional[Path | str] = None,
    resolve_secrets: bool = True,
    require_file: bool = False,
    **config_kwargs,
) -> ClientConfig

Resolve client settings, optionally skipping stored keyring secrets.

Keyword settings override config. An auth model or a dictionary containing auth_type replaces previous authentication settings, even when the type is unchanged. A dictionary without auth_type merges into the selected authentication configuration, including nested mappings; None values in partial overrides are ignored.

If a public configuration file exists and the resolved authentication lacks usable credentials, matching keyring secrets fill missing values. Explicitly supplied credentials take precedence, including after an auth replacement. Resolution does not rewrite the configuration file.

Set resolve_secrets=False to resolve the effective service and auth configuration without requiring readable keyring credentials.

Fresh settings combine the file, dotenv, process environment, supplied config fields, and keyword overrides in that order. Field defaults fill missing settings. A resolved config is a complete snapshot: wrapping it, including with overrides, does not reread these external sources. An explicitly different config_path selects a fresh profile instead. Secret lookup is independent and can be requested after initially resolving with resolve_secrets=False. require_file=True requires an existing, nonempty profile, as the CLI does.

from_file `classmethod`

from_file(
    config_path: Optional[str | Path] = None,
    *,
    config_type: type[ClientConfig] | None = None,
) -> Optional[ClientConfig]

Load a file using the application's configured schema.

Missing or empty files return None. Parsing or validation errors raise ValueError with instructions to run configure, without exposing file contents. Files that validate are accepted regardless of their age or field names. Loading does not rewrite the file, and filesystem access errors propagate unchanged.

read_file_data `classmethod`

read_file_data(
    config_path: Optional[str | Path] = None,
) -> dict[str, Any] | None

Read an unvalidated configuration mapping from a file, if it exists.

normalize_config_path `classmethod`

normalize_config_path(
    config_path: Path | str | None,
    *,
    config_type: type[ClientConfig] | None = None,
) -> Path

Return a path, using the selected application's default when absent.

new_instance `classmethod`

new_instance(
    *, config_type: type[ClientConfig] | None = None, **kwargs: Any
) -> ClientConfig

Validate supplied values and field defaults without reading sources.

to_dict

to_dict() -> dict[str, Any]

Return explicit input fields, retaining values equal to their defaults.

Nested models are complete selections, including their own defaults. In particular, an auth instance always carries its discriminator. This mapping is for resolution; to_file_dict is the secret-free disk format.

to_file_dict

to_file_dict() -> dict[str, Any]

Return a configuration mapping that omits authentication secrets.

validate_api_url

validate_api_url(v: str | None) -> str | None

Validate HTTP URLs as strings; leave base-path joining to consumers.

Empty values become None. Converting HttpUrl to str does not strip or append a slash beyond HttpUrl's own normalization.

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.

Each class starts with the built-ins and its extra_job_result_openers. Use it to register further custom openers for special job results.

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

Auth Configuration API

Warning

The Client Auth Configuration API is not stable and may change without notice. Do not yet rely on it.

OpenID Connect

OidcAuthConfig describes a public OIDC client through its issuer URL, client ID, and optional scopes. See Authentication for the login flow and credential lifecycle.

cuiman.api.auth

AuthConfig `module-attribute`

AuthConfig: TypeAlias = Annotated[
    NoAuthConfig
    | BasicAuthConfig
    | TokenAuthConfig
    | LoginAuthConfig
    | OAuth2AuthConfig
    | OidcAuthConfig
    | ApiKeyAuthConfig,
    Field(discriminator="auth_type"),
]

Discriminated union of authentication configuration models.

AuthType `module-attribute`

AuthType: TypeAlias = Literal[
    "none", "basic", "token", "login", "oauth2", "oidc", "api-key"
]

Authentication mechanism selected by an AuthConfig discriminator.

The allowed values select the corresponding configuration model and define how authentication headers or credentials are obtained:

"none" uses no authentication.
"basic" sends the configured username and password in an HTTP Basic Authorization header.
"token" uses a pre-existing access token, either as a Bearer Authorization header or in a configured custom header.
"login" obtains an access token from a proprietary username/password login endpoint before using it like token authentication.
"oauth2" obtains and renews access tokens through an OAuth2 token endpoint using either the password or client-credentials grant.
"oidc" obtains and renews access tokens through OpenID Connect Authorization Code with PKCE.
"api-key" sends the configured API key in its configured header.

OAuth2GrantType `module-attribute`

OAuth2GrantType: TypeAlias = Literal['password', 'client_credentials']

OAuth2 grants supported by Cuiman.

SecretFields `module-attribute`

SecretFields: TypeAlias = frozenset[str]

Names of authentication fields that must not be persisted.

ApiKeyAuthConfig

Bases: AuthConfigBase

API-key authentication configuration.

auth_headers `property`

auth_headers: dict[str, str]

Return the configured API-key header.

to_public_dict

to_public_dict() -> dict[str, object]

Return the configuration values that are safe to persist.

to_secret_dict

to_secret_dict() -> dict[str, str]

Return the configured secret values for operating-system storage.

set_secret_persistor

set_secret_persistor(persistor: Callable[[AuthConfigBase], None]) -> None

Set the callback used to persist refreshed authentication secrets.

persist_secrets

persist_secrets() -> None

Persist the current secrets when the configuration has a persistor.

AuthConfigBase

Bases: BaseModel

Base class for authentication configuration models.

secret_fields `class-attribute`

secret_fields: SecretFields = frozenset()

Fields that must not be persisted in a client configuration file.

auth_headers `property`

auth_headers: dict[str, str]

Return the HTTP authentication headers for this configuration.

to_public_dict

to_public_dict() -> dict[str, object]

Return the configuration values that are safe to persist.

to_secret_dict

to_secret_dict() -> dict[str, str]

Return the configured secret values for operating-system storage.

set_secret_persistor

set_secret_persistor(persistor: Callable[[AuthConfigBase], None]) -> None

Set the callback used to persist refreshed authentication secrets.

persist_secrets

persist_secrets() -> None

Persist the current secrets when the configuration has a persistor.

BasicAuthConfig

Bases: AuthConfigBase

HTTP Basic authentication configuration.

auth_headers `property`

auth_headers: dict[str, str]

Return an HTTP Basic Authorization header.

to_public_dict

to_public_dict() -> dict[str, object]

Return the configuration values that are safe to persist.

to_secret_dict

to_secret_dict() -> dict[str, str]

Return the configured secret values for operating-system storage.

set_secret_persistor

set_secret_persistor(persistor: Callable[[AuthConfigBase], None]) -> None

Set the callback used to persist refreshed authentication secrets.

persist_secrets

persist_secrets() -> None

Persist the current secrets when the configuration has a persistor.

LoginAuthConfig

Bases: _AccessTokenAuthConfig

Configuration for a proprietary username/password login endpoint.

access_token_header `class-attribute` `instance-attribute`

access_token_header: str | None = Field(default=None, min_length=1)

Custom header for the raw token; omitted means standard Bearer signing.

login_url `instance-attribute`

login_url: HttpUrl

Login endpoint, retained as a validated HttpUrl.

Converted to a string for the login request without API base-URL joining: /login and /login/ remain distinct endpoint paths. HttpUrl preserves a non-empty path's trailing slash but adds / to a bare host.

to_public_dict

to_public_dict() -> dict[str, object]

Return the configuration values that are safe to persist.

to_secret_dict

to_secret_dict() -> dict[str, str]

Return the configured secret values for operating-system storage.

set_secret_persistor

set_secret_persistor(persistor: Callable[[AuthConfigBase], None]) -> None

Set the callback used to persist refreshed authentication secrets.

persist_secrets

persist_secrets() -> None

Persist the current secrets when the configuration has a persistor.

NoAuthConfig

Bases: AuthConfigBase

Configuration for APIs that require no authentication.

secret_fields `class-attribute`

secret_fields: SecretFields = frozenset()

Fields that must not be persisted in a client configuration file.

auth_headers `property`

auth_headers: dict[str, str]

Return the HTTP authentication headers for this configuration.

to_public_dict

to_public_dict() -> dict[str, object]

Return the configuration values that are safe to persist.

to_secret_dict

to_secret_dict() -> dict[str, str]

Return the configured secret values for operating-system storage.

set_secret_persistor

set_secret_persistor(persistor: Callable[[AuthConfigBase], None]) -> None

Set the callback used to persist refreshed authentication secrets.

persist_secrets

persist_secrets() -> None

Persist the current secrets when the configuration has a persistor.

OAuth2AuthConfig

Bases: OAuthTokenConfig

OAuth2 password or client-credentials token endpoint configuration.

auth_headers `property`

auth_headers: dict[str, str]

Return the HTTP authentication headers for this configuration.

token_url `instance-attribute`

token_url: HttpUrl

OAuth2 token endpoint, retained as a validated HttpUrl.

Converted to a string for Authlib without API base-URL joining: /token and /token/ remain distinct endpoint paths. HttpUrl preserves a non-empty path's trailing slash but adds / to a bare host.

to_public_dict

to_public_dict() -> dict[str, object]

Return the configuration values that are safe to persist.

to_secret_dict

to_secret_dict() -> dict[str, str]

Serialize the complete token for the string-valued keyring record.

set_secret_persistor

set_secret_persistor(persistor: Callable[[AuthConfigBase], None]) -> None

Set the callback used to persist refreshed authentication secrets.

persist_secrets

persist_secrets() -> None

Persist the current secrets when the configuration has a persistor.

OidcAuthConfig

Bases: OAuthTokenConfig

OpenID Connect authorization-code configuration for a public PKCE client.

auth_headers `property`

auth_headers: dict[str, str]

Return the HTTP authentication headers for this configuration.

issuer_url `instance-attribute`

issuer_url: Annotated[HttpUrl, UrlConstraints(preserve_empty_path=True)]

OIDC issuer identifier used for exact discovery and ID-token matching.

preserve_empty_path=True also keeps https://identity.example distinct from https://identity.example/; ordinary HttpUrl fields add / to a bare host. A trailing slash is stripped only when building the discovery URL, never from the issuer identifier used for matching.

to_public_dict

to_public_dict() -> dict[str, object]

Return the configuration values that are safe to persist.

to_secret_dict

to_secret_dict() -> dict[str, str]

Serialize the complete token for the string-valued keyring record.

set_secret_persistor

set_secret_persistor(persistor: Callable[[AuthConfigBase], None]) -> None

Set the callback used to persist refreshed authentication secrets.

persist_secrets

persist_secrets() -> None

Persist the current secrets when the configuration has a persistor.

include_openid_scope

include_openid_scope() -> OidcAuthConfig

Include the required OpenID Connect scope without duplicates.

TokenAuthConfig

Bases: _AccessTokenAuthConfig

Static access-token authentication configuration.

access_token_header `class-attribute` `instance-attribute`

access_token_header: str | None = Field(default=None, min_length=1)

Custom header for the raw token; omitted means standard Bearer signing.

to_public_dict

to_public_dict() -> dict[str, object]

Return the configuration values that are safe to persist.

to_secret_dict

to_secret_dict() -> dict[str, str]

Return the configured secret values for operating-system storage.

set_secret_persistor

set_secret_persistor(persistor: Callable[[AuthConfigBase], None]) -> None

Set the callback used to persist refreshed authentication secrets.

persist_secrets

persist_secrets() -> None

Persist the current secrets when the configuration has a persistor.

LoginRequiredError

Bases: ValueError

Credentials or an explicit interactive login are required.

Job Result Opener API

cuiman.api.opener.JobResultOpener

Bases: ABC

Abstract base class for pluggable job result openers.

An opener implementation is free to use the information in the context object ctx passed to accept_job_result() and open_job_result(). However, if data_type or output_name are provided, an opener MUST be able to deal with them, otherwise accept_job_result() should return False.

is_usable `classmethod`

is_usable() -> bool

Check whether this opener is usable in the current OS or Python environment.

accept_job_result `abstractmethod` `async`

accept_job_result(ctx: JobResultOpenContext) -> bool

Check if this opener can potentially be used to open the given job result.

More specifically, the method is used to exclude this opener from the list of potential openers for the given job results.

For performance reasons, an implementation should focus on determining the unability to open the job results and early return False in this case.

The method is not expected to raise any errors.

Parameters:

Name	Type	Description	Default
`ctx`	`JobResultOpenContext`	The job result open context used to check.	required

Returns:

Type	Description
`bool`	`True` if this opener can open the job results, `False` otherwise.

open_job_result `abstractmethod` `async`

open_job_result(ctx: JobResultOpenContext) -> Any

Open the result of a job.

The method is expected to raise an appropriate error if it is not possible to open the job results.

Parameters:

Name	Type	Description	Default
`ctx`	`JobResultOpenContext`	The job result open context used to open.	required

Returns:

Type	Description
`Any`	The value from opening the job result.

cuiman.api.opener.JobResultOpenContext `dataclass`

JobResultOpenContext(
    config: ClientConfig,
    job_id: str,
    job_results: JobResults,
    process_description: ProcessDescription | None = None,
    output_name: str | None = None,
    data_type: type | None = None,
    _media_type: str | None = None,
    options: dict[str, Any] = dict(),
)

The context around the results of a process job that allows opening the job results or a particular job result. Includes job_results of type JobResults and the context surrounding it. The context object is passed to JobResultOpener.

config `instance-attribute`

config: ClientConfig

Configuration of the client.

job_id `instance-attribute`

job_id: str

ID of the job.

job_results `instance-attribute`

job_results: JobResults

Results of a job.

process_description `class-attribute` `instance-attribute`

process_description: ProcessDescription | None = None

Description of the process that produced the results.

output_name `class-attribute` `instance-attribute`

output_name: str | None = None

Name of the output that should be opened. If given, an opener must accept that name and be able to return a value of that name from the open_job_result() method.

data_type `class-attribute` `instance-attribute`

data_type: type | None = None

Data type of the output that should be opened. If given, an opener must accept that value and be able to return a value of that type from the open_job_result() method.

options `class-attribute` `instance-attribute`

options: dict[str, Any] = field(default_factory=dict)

Opener-specific options.

output_value `property`

output_value: Link | QualifiedValue | InlineValue | None

Output value.

If output_name is given, the value of that output. If output_name is not given, the job results must comprise only a single output or contain an output value named "return_value". Otherwise, the output value is None.

output_link `property`

output_link: Link | None

Output link. May be None if output_value is not a link.

output_qualified_value `property`

output_qualified_value: QualifiedValue | None

Qualified output value. May be None if output_value is not a qualified value.

output_media_type `property`

output_media_type: str | None

The output value's media type. If provided, the media type value is usually data format's MIME-type string. May be None if output_value does not have a media type assigned.

cuiman.api.opener.JobResultOpenerRegistry

JobResultOpenerRegistry()

A simple registry for job result openers.

opener_types `property`

opener_types: tuple[JobResultOpenerType, ...]

The tuple of registered job result openers.

create_default `classmethod`

create_default() -> JobResultOpenerRegistry

Create a registry that includes default job result openers.

register

register(opener_type: JobResultOpenerType) -> Callable[[], None]

Register a job result opener.

Parameters:

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

Returns:

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

clear

clear() -> None

Clears the registry. Removes registered all job result openers.

App API

cuiman.app.App

App(remote_store: rs.Store, serve_result: rs.ServeResult)

The app instance displayed and returned by Client.show_app(). It allows for convenient interaction with the app's data state,

remote_store `property`

remote_store: rs.Store

The app's remote store.

serve_result `property`

serve_result: rs.ServeResult

The result from remotestate.serve().

at `property`

at: rs.StoreAt

The underlying remotestore.StoreAt instance which provides access to the state data via keys, indexes, and attributes.

process_requests `property` `writable`

process_requests: rs.StoreAt

The remotestore.StoreAt instance that accesses the app's current process requests.

create_remote_store `classmethod`

create_remote_store() -> rs.Store

Create a new remotestate.Store instance for an app instance.

get_process_request

get_process_request(process_id: str) -> ProcessRequest | None

Get a process request.

set_process_request

set_process_request(
    process_id: str, process_request: ProcessRequestInput
) -> None

Set a process request.

CLI API

cuiman.cli.new_cli

new_cli(
    name: str = DEFAULT_NAME,
    help: str | None = None,
    summary: str | None = None,
    version: str | None = None,
    config_type: type[ClientConfig] | None = None,
) -> typer.Typer

Create a server CLI instance for the given, optional name and help text.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the CLI application. Defaults to `cuiman`.	`DEFAULT_NAME`
`help`	`str \| None`	Optional CLI application help text. If not provided, the default `cuiman` help text will be used.	`None`
`summary`	`str \| None`	A one-sentence human-readable description of the tool that will be used by the default help text. Hence, used only, if `help` is not provided. Should end with a dot '.'.	`None`
`version`	`str \| None`	Optional version string. If not provided, the `cuiman` version will be used.	`None`
`config_type`	`type[ClientConfig] \| None`	Application settings class. It supplies the CLI's schema, defaults, environment namespace, and default profile location. If omitted, `ClientConfig` is loaded when a command needs it.	`None`

Return: a typer.Typer instance

Cuiman API Reference

Client API

cuiman.api.Client

token property

close

login

logout

create_execution_request

open_job_result

show_app

get_capabilities

get_conformance

get_processes

get_process

execute_process

get_jobs

get_job

dismiss_job

get_job_results

cuiman.api.ClientError

Configuration API

cuiman.api.ClientConfig

default_path class-attribute

display_name class-attribute

cli_name class-attribute

return_type_map class-attribute

extra_job_result_openers class-attribute

api_url class-attribute instance-attribute

auth class-attribute instance-attribute

create classmethod

from_file classmethod

read_file_data classmethod

normalize_config_path classmethod

new_instance classmethod

to_dict

to_file_dict

validate_api_url

register_job_result_opener classmethod

get_job_result_opener_registry cached classmethod

Auth Configuration API

OpenID Connect

cuiman.api.auth

AuthConfig module-attribute

AuthType module-attribute

OAuth2GrantType module-attribute

SecretFields module-attribute

ApiKeyAuthConfig

auth_headers property

to_public_dict

to_secret_dict

set_secret_persistor

persist_secrets

AuthConfigBase

secret_fields class-attribute

auth_headers property

to_public_dict

to_secret_dict

set_secret_persistor

persist_secrets

BasicAuthConfig

auth_headers property

to_public_dict

to_secret_dict

set_secret_persistor

persist_secrets

LoginAuthConfig

access_token_header class-attribute instance-attribute

login_url instance-attribute

to_public_dict

to_secret_dict

set_secret_persistor

persist_secrets

NoAuthConfig

secret_fields class-attribute

auth_headers property

to_public_dict

to_secret_dict

set_secret_persistor

persist_secrets

OAuth2AuthConfig

token `property`

default_path `class-attribute`

display_name `class-attribute`

cli_name `class-attribute`

return_type_map `class-attribute`

extra_job_result_openers `class-attribute`

api_url `class-attribute` `instance-attribute`

auth `class-attribute` `instance-attribute`

create `classmethod`

from_file `classmethod`

read_file_data `classmethod`

normalize_config_path `classmethod`

new_instance `classmethod`

register_job_result_opener `classmethod`

get_job_result_opener_registry `cached` `classmethod`

AuthConfig `module-attribute`

AuthType `module-attribute`

OAuth2GrantType `module-attribute`

SecretFields `module-attribute`

auth_headers `property`

secret_fields `class-attribute`

auth_headers `property`

auth_headers `property`

access_token_header `class-attribute` `instance-attribute`

login_url `instance-attribute`

secret_fields `class-attribute`

auth_headers `property`

auth_headers `property`

token_url `instance-attribute`

auth_headers `property`

issuer_url `instance-attribute`

access_token_header `class-attribute` `instance-attribute`

is_usable `classmethod`

accept_job_result `abstractmethod` `async`

open_job_result `abstractmethod` `async`

cuiman.api.opener.JobResultOpenContext `dataclass`

config `instance-attribute`

job_id `instance-attribute`

job_results `instance-attribute`

process_description `class-attribute` `instance-attribute`

output_name `class-attribute` `instance-attribute`

data_type `class-attribute` `instance-attribute`

options `class-attribute` `instance-attribute`

output_value `property`

output_link `property`

output_qualified_value `property`

output_media_type `property`

opener_types `property`

create_default `classmethod`

remote_store `property`

serve_result `property`

at `property`

process_requests `property` `writable`

create_remote_store `classmethod`