weaver.cli
Module Contents
- class weaver.cli.OperationResult(success: bool | None = None, message: str | None = None, body: str | weaver.typedefs.JSON | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, text: str | None = None, code: int | None = None, **kwargs)[source]
Data container for any
WeaverClient
operation results.- Parameters:
success – Success status of the operation.
message – Detail extracted from response content if available.
headers – Headers returned by the response for reference.
body – Content of JSON response or fallback in plain text.
text – Pre-formatted text representation of
body
.
Initialize self. See help(type(self)) for accurate signature.
- class weaver.cli.AuthHandler(identity: str | None = None, password: str | None = None, url: str | None = None, method: weaver.typedefs.AnyRequestMethod = 'GET', headers: weaver.typedefs.AnyHeadersContainer | None = None)[source]
Base class that all auth implementations derive from
- class weaver.cli.BasicAuthHandler(username: str, password: str, **kwargs: Any)[source]
Adds the
Authorization
header formed from basic authentication encoding of username and password to the request.Authentication URL and method are not needed for this handler.
- class weaver.cli.RequestAuthHandler(identity: str | None = None, password: str | None = None, url: str | None = None, method: weaver.typedefs.AnyRequestMethod = 'GET', headers: weaver.typedefs.AnyHeadersContainer | None = None, token: str | None = None)[source]
Base class to send a request in order to retrieve an authorization token.
- property auth_token_name: str[source]
Override token name to retrieve in response authentication handler implementation.
Default looks amongst common names: [auth, access_token, token]
- abstract auth_header(token: str) weaver.typedefs.AnyHeadersContainer [source]
Obtain the header definition with the provided authorization token.
- static parse_token(token: Any) str [source]
- Abstractmethod:
Convert token to a form that can be included in a request header.
- class weaver.cli.BearerAuthHandler(identity: str | None = None, password: str | None = None, url: str | None = None, method: weaver.typedefs.AnyRequestMethod = 'GET', headers: weaver.typedefs.AnyHeadersContainer | None = None, token: str | None = None)[source]
Adds the
Authorization
header formed of the authentication bearer token from the underlying request.
- class weaver.cli.CookieAuthHandler(identity: str | None = None, password: str | None = None, url: str | None = None, method: weaver.typedefs.AnyRequestMethod = 'GET', headers: weaver.typedefs.AnyHeadersContainer | None = None, token: str | weaver.typedefs.CookiesType | None = None)[source]
Adds the
Cookie
header formed from the authentication bearer token from the underlying request.- static parse_token(token: str | weaver.typedefs.CookiesType) str [source]
Convert token to a form that can be included in a request header.
Returns the token string as is if it is a string. Otherwise, if the token is a mapping, where keys are cookie names and values are cookie values, convert the cookie representation to a string that can be accepted as the value of the “Cookie” header.
- class weaver.cli.WeaverClient(url: str | None = None, auth: requests.auth.AuthBase | None = None)[source]
Client that handles common HTTP requests with a Weaver or similar OGC API - Processes instance.
Initialize the client with predefined parameters.
- Parameters:
url – Instance URL to employ for each method call. Must be provided each time if not defined here.
auth – Instance authentication handler that will be applied for every request. For specific authentication method on per-request basis, parameter should be provided to respective methods. Should perform required adjustments to request to allow access control of protected contents.
- auth: AuthHandler = None[source]
- _request(method: weaver.typedefs.AnyRequestMethod, url: str, headers: weaver.typedefs.AnyHeadersContainer | None = None, x_headers: weaver.typedefs.AnyHeadersContainer | None = None, request_timeout: int | None = None, request_retries: int | None = None, **kwargs) weaver.typedefs.AnyResponseType [source]
- static _parse_result(response: requests.Response | OperationResult, body: weaver.typedefs.JSON | None = None, message: str | None = None, success: bool | None = None, with_headers: bool = False, with_links: bool = True, nested_links: str | None = None, output_format: weaver.formats.AnyOutputFormat | None = None, content_type: weaver.formats.ContentType | None = None) OperationResult [source]
- static _parse_deploy_body(body: weaver.typedefs.JSON | str | None, process_id: str | None) OperationResult [source]
- static _parse_deploy_package(body: weaver.typedefs.JSON, cwl: weaver.typedefs.CWL | str | None, wps: str | None, process_id: str | None, headers: weaver.typedefs.HeadersType, settings: weaver.typedefs.SettingsType) OperationResult [source]
- _parse_job_ref(job_reference: weaver.typedefs.URL | weaver.typedefs.AnyUUID, url: str | None = None) Tuple[str | None, str | None] [source]
- static _parse_auth_token(token: str | None, username: str | None, password: str | None) weaver.typedefs.HeadersType [source]
- info(url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Retrieve server information from the landing page.
- Parameters:
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- version(url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Retrieve server version.
- Parameters:
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- conformance(category: weaver.wps_restapi.constants.AnyConformanceCategory | None = None, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Retrieve server conformance classes.
- Parameters:
category – Select the category of desired conformance item references to be returned.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- register(provider_id: str, provider_url: str, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Registers a remote Provider using specified references.
Note
This operation is specific to Weaver. It is not supported by standard OGC API - Processes.
- Parameters:
provider_id – Identifier to employ for registering the new Provider.
provider_url – Endpoint location to register the new remote Provider.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- unregister(provider_id: str, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Unregisters a remote Provider using the specified identifier.
Note
This operation is specific to Weaver. It is not supported by standard OGC API - Processes.
- Parameters:
provider_id – Identifier to employ for unregistering the Provider.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- deploy(process_id: str | None = None, body: weaver.typedefs.JSON | str | None = None, cwl: weaver.typedefs.CWL | str | None = None, wps: str | None = None, token: str | None = None, username: str | None = None, password: str | None = None, undeploy: bool = False, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Deploy a new Process with specified metadata and reference to an Application Package.
The referenced Application Package must be one of: - CWL body, local file or URL in JSON or YAML format - WPS process URL with XML response - WPS-REST process URL with JSON response - OGC API - Processes process URL with JSON response
If the reference is resolved to be a Workflow, all its underlying Process steps must be available under the same URL that this client was initialized with.
Note
This is only supported by OGC API - Processes instances that support the Deploy, Replace, Undeploy (DRU) extension.
See also
- Parameters:
process_id – Desired process identifier. Can be omitted if already provided in body contents or file.
body – Literal JSON contents, either using string representation of actual Python objects forming the request body, or file path/URL to YAML or JSON contents of the request body. Other parameters (
process_id
,cwl
) can override corresponding fields within the provided body.cwl – Literal JSON or YAML contents, either using string representation of actual Python objects, or file path/URL with contents of the CWL definition of the Application package to be inserted into the body.
wps – URL to an existing WPS process (WPS-1/2 or WPS-REST/OGC-API).
token – Authentication token for accessing private Docker registry if CWL refers to such image.
username – Username to form the authentication token to a private Docker registry.
password – Password to form the authentication token to a private Docker registry.
undeploy – Perform undeploy as necessary before deployment to avoid conflict with exiting Process.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- undeploy(process_id: str, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Undeploy an existing Process.
- Parameters:
process_id – Identifier of the process to undeploy.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- capabilities(url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, with_providers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None, sort: weaver.sort.Sort | None = None, page: int | None = None, limit: int | None = None, detail: bool = False) OperationResult [source]
List all available Process on the instance.
- Parameters:
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
with_providers – Indicate if remote providers should be listed as well along with local processes.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
sort – Sorting field to list processes. Name must be one of the fields supported by process objects.
page – Paging index to list processes.
limit – Amount of processes to list per page.
detail – Obtain detailed process descriptions.
- Returns:
Results of the operation.
- processes[source]
Alias of
capabilities()
for Process listing.
- describe(process_id: str, provider_id: str | None = None, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, schema: weaver.processes.constants.ProcessSchemaType | None = ProcessSchema.OGC, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Describe the specified Process.
- Parameters:
process_id – Identifier of the local or remote process to describe.
provider_id – Identifier of the provider from which to locate a remote process to describe.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
schema – Representation schema of the returned process description.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- package(process_id: str, provider_id: str | None = None, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Retrieve the Application Package definition of the specified Process.
Note
This operation is specific to Weaver. It is not supported by standard OGC API - Processes.
- Parameters:
process_id – Identifier of the local or remote process to describe.
provider_id – Identifier of the provider from which to locate a remote process to describe.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- static _parse_inputs(inputs: str | weaver.typedefs.ExecutionInputs | weaver.typedefs.CWL_IO_ValueMap | None) OperationResult | weaver.typedefs.ExecutionInputsMap [source]
Parse multiple different representation formats and input sources into standard OGC inputs.
Schema OGC is selected to increase compatibility coverage with potential non-Weaver servers only conforming to standard OGC API - Processes.
Inputs can be represented as CLI option string arguments, file path to load contents from, or directly supported list or mapping of execution inputs definitions.
- _upload_files(inputs: weaver.typedefs.ExecutionInputsMap, url: str | None = None) Tuple[weaver.typedefs.ExecutionInputsMap, weaver.typedefs.HeadersType] | OperationResult [source]
Replaces local file paths by references uploaded to the Vault.
See also
Headers dictionary limitation by
requests
: https://requests.readthedocs.io/en/master/user/quickstart/#response-contentHeaders formatting with multiple values must be provided by comma-separated values (RFC 7230#section-3.2.2).
Multi Vault-Token parsing accomplished by
weaver.vault.utils.parse_vault_token()
.More details about formats and operations related to Vault are provided in File Vault Inputs and Uploading File to the Vault chapters.
- Parameters:
inputs – Input values for submission of Process execution.
- Returns:
Updated inputs or the result of a failing intermediate request.
- _prepare_inputs(inputs: str | weaver.typedefs.ExecutionInputs | weaver.typedefs.CWL_IO_ValueMap | None = None, url: str | None = None) Tuple[weaver.typedefs.ExecutionInputsMap, weaver.typedefs.HeadersType] | OperationResult [source]
Performs operations needed to prepare inputs, including parsing provided data/reference and upload as needed.
- Returns:
Operation result is returned in case of any failure. Otherwise, returns the parsed inputs and upload access tokens (as applicable).
- _prepare_outputs(body: weaver.typedefs.JSON, output_ids: List[str], output_refs: Iterable[str] | None = None, output_filter: Sequence[str] | None = None) weaver.typedefs.JSON [source]
Performs inplace replacement or update of Job outputs according to predefined and requested conditions.
- execute(process_id: str, provider_id: str | None = None, inputs: str | weaver.typedefs.ExecutionInputs | weaver.typedefs.CWL_IO_ValueMap | None = None, pending: bool = False, monitor: bool = False, timeout: int | None = None, interval: int | None = None, subscribers: weaver.typedefs.JobSubscribers | None = None, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_type: Literal['core', 'jobs'] = 'core', request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None, output_refs: Iterable[str] | None = None, output_filter: Sequence[str] | None = None, output_context: str | None = None) OperationResult [source]
Execute a Job for the specified Process with provided inputs.
When submitting inputs with OGC API - Processes schema, top-level
inputs
field is expected. Under this field, either the OGC mapping (key-value) or listing (id,value) representations are accepted.If the top-level
inputs
field is not found, the alternative CWL representation will be assumed. When submitting inputs with CWL job schema, plain key-value(s) pairs are expected. All values should be provided directly under the key (including arrays), except forFile
type that must include details as theclass: File
andpath
with location.Note
Execution requests are always accomplished asynchronously. To obtain the final Job status as if they were executed synchronously, provide the
monitor
argument. This offers more flexibility over servers that could decide to ignore sync/async preferences, and avoids closing/timeout connection errors that could occur for long-running processes, since status is pooled iteratively rather than waiting.- Parameters:
process_id – Identifier of the local or remote process to execute.
provider_id – Identifier of the provider from which to locate a remote process to execute.
inputs – Literal JSON or YAML contents of the inputs submitted and inserted into the execution body, using either the OGC API - Processes or CWL format, or a file path/URL referring to them.
pending – If enabled, the Job will be created, but will not immediately start execution. The Job will be pending execution until a following
trigger_job()
is sent. When enabled,monitor
parameter is ignored since it is expected that no execution will occur. Also, therequest_path
will be enforced to"jobs"
since this is the only one supporting it.monitor – Automatically perform Job execution monitoring until completion or timeout to obtain final results. If requested, this operation will become blocking until either the completed status or timeout is reached.
timeout – Monitoring timeout (seconds) if requested.
interval – Monitoring interval (seconds) between job status polling requests.
subscribers – Job status subscribers to obtain email or callback request notifications. The subscriber keys indicate which type of subscriber and for which status the notification will be sent.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_type – Whether to employ the OGC API - Processes Part 1: Core endpoint (i.e.:
/processes/{processID}/execution
) or the OGC API - Processes Part 4: Job Management endpoint (i.e.:/jobs
) to submit the Job execution. The request type behave the same way regardless of the selected endpoint when targeting a Weaver instance. Selection is provided in case the choice impacts another non-Weaver instance for which a specific endpoint must be employed by the client. This option is enforced to"jobs"
ifpending
is requested.request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
output_refs – Indicates which outputs by ID to be returned as HTTP Link header reference instead of body content value. With reference transmission mode, outputs that contain literal data will be linked by
text/plain
file containing the data. outputs that refer to a file reference will simply contain that URL reference as link. With value transmission mode (default behavior when outputs are not specified in this list), outputs are returned as direct values (literal or href) within the response content body.output_filter – Indicates a list of outputs to omit from the results. If unspecified (default), all outputs are returned.
output_context – Specify an output context for which the Weaver instance should attempt storing the Job results under the nested location of its configured WPS outputs. Note that the instance is not required to fulfill that preference, and can ignore this value if it deems that the provided context is inadequate.
- Returns:
Results of the operation.
- trigger_job(job_reference: weaver.typedefs.URL | weaver.typedefs.AnyUUID, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Trigger a pending Job execution.
To submit a pending Job, see the
pending
parameter ofexecute()
.This call only applies to a Job that is
Status.CREATED
. Otherwise, an error should be returned by the API since the operation doesn’t apply for an already submitted, running or completed Job. Once triggered, themonitor()
operation should be used to track the Job progress until completion.- Parameters:
job_reference – Either the full Job status URL or only its UUID.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Result of the Job trigger operation.
- update_job(job_reference: weaver.typedefs.URL | weaver.typedefs.AnyUUID, title: Type[weaver.utils.null] | str | None = null, inputs: str | weaver.typedefs.ExecutionInputs | weaver.typedefs.CWL_IO_ValueMap | None = None, subscribers: weaver.typedefs.JobSubscribers | None = None, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None, output_refs: Iterable[str] | None = None, output_filter: Sequence[str] | None = None, output_context: str | None = None) OperationResult [source]
Trigger a pending Job execution.
To submit a pending Job, see the
pending
parameter ofexecute()
.This call only applies to a Job that is
Status.CREATED
. Otherwise, an error should be returned by the API since the operation doesn’t apply for an already submitted, running or completed Job. Once triggered, themonitor()
operation should be used to track the Job progress until completion.To evaluate the current state of the inputs of a pending Job, it is recommended to employ the
inputs()
operation. This can be used in unison withupdate_job()
to iteratively adjust the Job configuration until it is ready fortrigger_job()
execution.- Parameters:
job_reference – Either the full Job status URL or only its UUID.
title – Title value to update. Note that an explicit
None
unsets the title.inputs – Literal JSON or YAML contents of the inputs submitted and inserted into the execution body, using either the OGC API - Processes or CWL format, or a file path/URL referring to them.
subscribers – Job status subscribers for email or callback request notifications to be updated. The subscriber keys indicate which type of subscriber and for which status the notification will be sent. Note that modifying this value will override any previously configured subscribers on the job. Therefore, any update must re-submit any previously submitted subscribers to achieve an ‘additive’ result. If an empty mapping is submitted, all subscribers will be cleared.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
output_refs – Indicates which outputs by ID to be returned as HTTP Link header reference instead of body content value. With reference transmission mode, outputs that contain literal data will be linked by
text/plain
file containing the data. outputs that refer to a file reference will simply contain that URL reference as link. With value transmission mode (default behavior when outputs are not specified in this list), outputs are returned as direct values (literal or href) within the response content body.output_filter – Indicates a list of outputs to omit from the results. If unspecified (default), all outputs are returned.
output_context – Specify an output context for which the Weaver instance should attempt storing the Job results under the nested location of its configured WPS outputs. Note that the instance is not required to fulfill that preference, and can ignore this value if it deems that the provided context is inadequate.
- Returns:
Result of the Job update operation.
- upload(file_path: str, content_type: str | None = None, content_encoding: weaver.formats.ContentEncoding | None = None, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Upload a local file to the Vault.
Note
Feature only available for Weaver instances. Not available for standard OGC API - Processes.
See also
More details about formats and operations related to Vault are provided in File Vault Inputs and Uploading File to the Vault chapters.
- Parameters:
file_path – Location of the file to be uploaded.
content_type – Explicit Content-Type of the file. This should be an IANA Media-Type, optionally with additional parameters such as charset. If not provided, attempts to guess it based on the file extension.
content_encoding – Specify the Content-Encoding of the file. For text use
utf-8
or leaveNone
. For binary usebase64
orbinary
.url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Results of the operation.
- jobs(url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None, sort: weaver.sort.Sort | None = None, page: int | None = None, limit: int | None = None, status: weaver.status.AnyStatusSearch | List[weaver.status.AnyStatusSearch] | None = None, detail: bool = False, groups: bool = False, process: str | None = None, provider: str | None = None, tags: str | List[str] | None = None) OperationResult [source]
Obtain a listing of Job.
- Parameters:
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
sort – Sorting field to list jobs. Name must be one of the fields supported by job objects.
page – Paging index to list jobs.
limit – Amount of jobs to list per page.
status – Filter job listing only to matching status. If multiple are provided, must match one of them.
detail – Obtain detailed job descriptions.
groups – Obtain grouped representation of jobs per provider and process categories.
process – Obtain jobs executed only by matching Process.
provider – Obtain jobs only matching remote Provider.
tags – Obtain jobs filtered by matching tags. Jobs must match all tags simultaneously, not one of them.
- Returns:
Retrieved status of the job.
- status(job_reference: weaver.typedefs.URL | weaver.typedefs.AnyUUID, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Obtain the status of a Job.
- Parameters:
job_reference – Either the full Job status URL or only its UUID.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Retrieved status of the Job.
- _job_info(x_path: str, job_reference: weaver.typedefs.URL | weaver.typedefs.AnyUUID, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Obtain the information from a Job.
The Job must be in the expected status to retrieve relevant information.
- Parameters:
job_reference – Either the full Job status URL or only its UUID.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Retrieved information from the Job.
- provenance(job_reference: weaver.typedefs.URL | weaver.typedefs.AnyUUID, prov: weaver.provenance.ProvenancePathType | None = None, prov_run_id: weaver.typedefs.AnyUUID | None = None, prov_format: weaver.provenance.ProvenanceFormat | None = None, output_format: weaver.formats.AnyOutputFormat | None = None, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, **kwargs) OperationResult [source]
Obtain the Provenance metadata from a successful Job execution.
The Job must be in the expected status to retrieve relevant information.
- Parameters:
job_reference – Either the full Job status URL or only its UUID.
prov – Type of Provenance metadata to retrieve, as expressed by relative path. For example, retrieving an execution run metadata can be requested with
run
,/run
or/prov/run
. Available relative paths are as per defined by the API endpoints (seeProvenancePathType
). Can be combined in certain cases with arun_id
to obtain only the metadata of a nested step within a Workflow execution. If omitted, returns the main Provenance metadata representation as per the requestedprov_format
(seeProvenanceFormat
).prov_run_id – Specific run (i.e.: a nested Workflow step) for which to retrieve Provenance metadata. Applicable IDs will typically correspond to the underlying Job ID that would have been created for the corresponding steps, but could differ in particular situations. To make sure, the top-most
PROV
metadata should be inspected to extract relevant run IDs.prov_format – Desired Provenance metadata representation (see
ProvenanceFormat
). Applicable only when retrieving thePROV
details (i.e.:prov
must beNone
or/prov
). Ignored otherwise. Can be combined withoutput_format
to convert the representation into semantically equivalent representations. For example,ProvenanceFormat.PROV_JSON
could be converted into the corresponding YAML representation usingOutputFormat.YAML
. However, this is limited only to directly mappable representations (i.e.: JSON, YAML, XML).output_format – Select an alternate output representation of the result body contents. See also
prov_format
for even more format combinations specific to Provenance metadata.url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
- Returns:
Retrieved information from the Job.
- monitor(job_reference: str, timeout: int | None = None, interval: int | None = None, wait_for_status: str = Status.SUCCESSFUL, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Monitor the execution of a Job until completion.
- Parameters:
job_reference – Either the full Job status URL or only its UUID.
timeout – timeout (seconds) of maximum wait time for monitoring if completion is not reached.
interval – wait interval (seconds) between polling monitor requests.
wait_for_status – monitor until the requested status is reached (default: job failed or succeeded).
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Result of the successful or failed job, or timeout of monitoring process.
- _download_references(outputs: weaver.typedefs.ExecutionResults, out_links: weaver.typedefs.AnyHeadersContainer, out_dir: str, job_id: str, auth: requests.auth.AuthBase | None = None) weaver.typedefs.ExecutionResults [source]
Download file references from results response contents and link headers.
Downloaded files extend the results contents with
path
andsource
fields to indicate where the retrieved files have been saved and where they came from. When files are found by HTTP header links, they are added to the output contents to generate a combined representation in the operation result.
- results(job_reference: str, out_dir: str | None = None, download: bool = False, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None, output_links: Sequence[str] | None = None) OperationResult [source]
Obtain the results of a successful Job execution.
- Parameters:
job_reference – Either the full Job status URL or only its UUID.
out_dir – Output directory where to store downloaded files if requested (default: CURDIR/JobID/<outputs>).
download – Download any file reference found within results (CAUTION: could transfer lots of data!).
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
output_links – Output IDs that are expected in
Link
headers, and that should be retrieved (or downloaded) as results. This is not performed automatically since there can be a lot ofLinks
in responses, and output IDs could have conflictingrel
names with other indicative links.
- Returns:
Result details and local paths if downloaded.
- dismiss(job_reference: str, url: str | None = None, auth: requests.auth.AuthBase | None = None, headers: weaver.typedefs.AnyHeadersContainer | None = None, with_links: bool = True, with_headers: bool = False, request_timeout: int | None = None, request_retries: int | None = None, output_format: weaver.formats.AnyOutputFormat | None = None) OperationResult [source]
Dismiss pending or running Job, or clear result artifacts from a completed Job.
- Parameters:
job_reference – Either the full Job status URL or only its UUID.
url – Instance URL if not already provided during client creation.
auth – Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents.
headers – Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care.
with_links – Indicate if
links
section should be preserved in returned result body.with_headers – Indicate if response headers should be returned in result output.
request_timeout – Maximum timout duration (seconds) to wait for a response when performing HTTP requests.
request_retries – Amount of attempt to retry HTTP requests in case of failure.
output_format – Select an alternate output representation of the result body contents.
- Returns:
Obtained result from the operation.
- weaver.cli.setup_logger_from_options(logger: logging.Logger, args: argparse.Namespace) None [source]
Uses argument parser options to configure logging level from specified flags.
Setup both the specific CLI logger that is provided and the top-level package logger.
- weaver.cli.make_logging_options(parser: argparse.ArgumentParser) None [source]
Defines argument parser options for logging operations.
- weaver.cli.add_url_param(parser: argparse.ArgumentParser, required: bool = True) None [source]
- weaver.cli.add_listing_options(parser: argparse.ArgumentParser, item: str) None [source]
- weaver.cli.parse_auth(kwargs: Dict[str, Type[AuthHandler] | str | None]) AuthHandler | None [source]
Parses arguments that can define an authentication handler and remove them from dictionary for following calls.
- weaver.cli.add_provider_param(parser: argparse.ArgumentParser, description: str | None = None, required: bool = True) None [source]
- weaver.cli.add_process_param(parser: argparse.ArgumentParser, description: str | None = None, required: bool = True) None [source]
- weaver.cli.add_job_ref_param(parser: argparse.ArgumentParser) None [source]
- weaver.cli.add_job_title_param(parser: argparse.ArgumentParser) None [source]
- weaver.cli.add_job_exec_param(parser: argparse.ArgumentParser) None [source]
- weaver.cli.add_timeout_param(parser: argparse.ArgumentParser) None [source]
- weaver.cli.add_provenance_params(parser: argparse.ArgumentParser) None [source]
- weaver.cli.check_compatible_prov_formats(ns: argparse.Namespace) str | None [source]
Check multiple output format and PROV format for valid combinations.
If valid, update the arguments to make them work during invocation. Otherwise, return the relevant error to fail argument validation and print the error message.
- class weaver.cli.SubscriberAction(option_strings: List[str], dest: str = None, **kwargs: Any)[source]
Action that will validate that the input argument references a valid subscriber argument.
If valid, the returned value will be an updated subscriber definition. All arguments using
action=SubscriberType
should include adest="<holder>.<subscriber>"
parameter that will map thesubscriber
value under a dictionaryholder
that will be passed to theargparse.Namespace
.
- weaver.cli.add_subscribers_params(parser: argparse.ArgumentParser) None [source]
- weaver.cli.set_parser_sections(parser: argparse.ArgumentParser) None [source]
- class weaver.cli.ValidateAuthHandlerAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]
Action that will validate that the input argument references an authentication handler that can be resolved.
- class weaver.cli.ValidateMethodAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]
Action that will validate that the input argument one of the accepted HTTP methods.
- class weaver.cli.ValidateHeaderAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]
Action that will validate that the input argument is a correctly formed HTTP header name.
Each header should be provided as a separate option using format:
Header-Name: Header-Value
- class weaver.cli.ValidateNonZeroPositiveNumberAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]
Action that will validate that the input argument is a positive number greater than zero.
- class weaver.cli.ParagraphFormatter(prog, indent_increment=2, max_help_position=24, width=None)[source]
Formatter for generating usage messages and argument help strings.
Only the name of this class is considered a public API. All the methods provided by the class are considered an implementation detail.
- _format_action(action: argparse.Action) str [source]
Override the returned help message with available options and shortcuts for description paragraphs.
This ensures that paragraphs defined the argument’s help remain separated and properly formatted.
- class weaver.cli.SubArgumentParserFixedMutexGroups(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)[source]
Patch incorrectly handled mutually exclusive groups sections in subparsers.
- class weaver.cli.ArgumentParserFixedRequiredArgs(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)[source]
Override action grouping under ‘required’ section to consider explicit flag even if action has option prefix.
Default behaviour places option prefixed (
-
,--
) arguments into optionals even ifrequired
is defined. Help string correctly considers this flag and doesn’t place those arguments in brackets ([--<optional-arg>]
).
- class weaver.cli.WeaverSubParserAction(option_strings, prog, parser_class, dest=SUPPRESS, required=False, help=None, metavar=None)[source]
Parser that provides fixes for proper representation of Weaver CLI operations.
- class weaver.cli.WeaverArgumentParser(*args: Any, **kwargs: Any)[source]
Parser that provides fixes for proper representation of Weaver CLI arguments.
- property help_mode[source]
Option enabled only during help formatting to generate different conditional evaluations.
- add_help_conditional(container: argparse._ActionsContainer, help_required: bool = True, use_required: bool = False) argparse._ActionsContainer [source]
- parse_known_args(args: Sequence[str] | None = None, namespace: argparse.Namespace | None = None) Tuple[argparse.Namespace, Sequence[str]] [source]
Parse argument actions with handling of additional rules if any were defined.
Note
It is important to derive and call
parse_known_args()
rather thanparse_args()
to ensure nested subparsers rules validation can also be invoked.
- weaver.cli.make_parser() argparse.ArgumentParser [source]
Generate the CLI parser.
Note
Instead of employing
argparse.ArgumentParser
instances returned byargparse._SubParsersAction.add_parser()
, distinctargparse.ArgumentParser
instances are created for each operation and then merged back by ourselves as subparsers under the main parser. This provides more flexibility in arguments passed down and resolves, amongst other things, incorrect handling of exclusive argument groups and their grouping under corresponding section titles.