weaver.cli
Module Contents
- class weaver.cli.OperationResult(success: Optional[bool] = None, message: Optional[str] = None, body: Optional[Union[str, weaver.typedefs.JSON]] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, text: Optional[str] = None, code: Optional[int] = 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.
- links(self: Optional[List[str]], header_names=None) webob.headers.ResponseHeaders [source]
Obtain HTTP headers sorted in the result that corresponds to any link reference.
- Parameters
header_names – Limit link names to be considered. By default, considered headers are
Link
,Content-Location
andLocation
.
- class weaver.cli.WeaverClient(url=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.
- processes[source]
Alias of
capabilities()
for Process listing.
- static _parse_result(response: Ellipsis, body: Optional[weaver.typedefs.JSON] = None, message: Optional[str] = None, success: Optional[bool] = None, show_headers: bool = False, show_links: bool = True, nested_links: Optional[str] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) OperationResult [source]
- static _parse_deploy_body(body: Optional[Union[weaver.typedefs.JSON, str]], process_id: Optional[str]) OperationResult [source]
- static _parse_deploy_package(body: weaver.typedefs.JSON, cwl: Optional[weaver.typedefs.CWL], wps: Optional[str], process_id: Optional[str], headers: weaver.typedefs.HeadersType) OperationResult [source]
- _parse_job_ref(self: str, job_reference: Optional[str], url=None) Tuple[Optional[str], Optional[str]] [source]
- static _parse_auth_token(token: Optional[str], username: Optional[str], password: Optional[str]) weaver.typedefs.HeadersType [source]
- deploy(self: Ellipsis, process_id: Optional[str] = None, body: Optional[Union[weaver.typedefs.JSON, str]] = None, cwl: Optional[Union[weaver.typedefs.CWL, str]] = None, wps: Optional[str] = None, token: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, undeploy: bool = False, url: Optional[str] = None, show_links: bool = True, show_headers: bool = False, output_format: Optional[weaver.formats.AnyOutputFormat] = 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.
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.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
output_format – Select an alternate output representation of the result body contents.
- Returns
Results of the operation.
- undeploy(self: str, process_id: Optional[str], url: bool = None, show_links: bool = True, show_headers: Optional[weaver.formats.AnyOutputFormat] = False, output_format=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.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
output_format – Select an alternate output representation of the result body contents.
- Returns
Results of the operation.
- capabilities(self: Optional[str], url: bool = None, show_links: bool = True, show_headers: Optional[weaver.formats.AnyOutputFormat] = False, output_format=None) OperationResult [source]
List all available Process on the instance.
- Parameters
url – Instance URL if not already provided during client creation.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
output_format – Select an alternate output representation of the result body contents.
- Returns
Results of the operation.
- describe(self: Ellipsis, process_id: str, url: Optional[str] = None, schema: Optional[weaver.processes.constants.ProcessSchemaType] = ProcessSchema.OGC, show_links: bool = True, show_headers: bool = False, output_format: Optional[weaver.formats.AnyOutputFormat] = None) OperationResult [source]
Describe the specified Process.
- Parameters
process_id – Identifier of the process to describe.
url – Instance URL if not already provided during client creation.
schema – Representation schema of the returned process description.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
output_format – Select an alternate output representation of the result body contents.
- Returns
Results of the operation.
- static _parse_inputs(inputs: Optional[Union[str, weaver.typedefs.JSON]]) Union[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.
- _update_files(self: weaver.typedefs.ExecutionInputsMap, inputs: Optional[str], url=None) Union[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://docs.python-requests.org/en/latest/user/quickstart/#response-headersHeaders 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.
- execute(self: Ellipsis, process_id: str, inputs: Optional[Union[str, weaver.typedefs.JSON]] = None, monitor: bool = False, timeout: Optional[int] = None, interval: Optional[int] = None, url: Optional[str] = None, show_links: bool = True, show_headers: bool = False, output_format: Optional[weaver.formats.AnyOutputFormat] = None, output_refs: Optional[Iterable[str]] = None) OperationResult [source]
Execute a Job for the specified Process with provided inputs.
When submitting inputs with OGC API - Processes schema, top-level
inputs
key is expected. Under it, either the mapping (key-value) or listing (id,value) representation are accepted. Ifinputs
is not found, the alternative CWL 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 for
File
type that must include theclass
andpath
details.See also
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 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.
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.
url – Instance URL if not already provided during client creation.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
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.
- Returns
Results of the operation.
- upload(self: str, file_path: Optional[str], content_type: Optional[str] = None, url: bool = None, show_links: bool = True, show_headers: Optional[weaver.formats.AnyOutputFormat] = False, output_format=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.
url – Instance URL if not already provided during client creation.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
output_format – Select an alternate output representation of the result body contents.
- Returns
Results of the operation.
- jobs(self: Ellipsis, url: Optional[str] = None, show_links: bool = True, show_headers: bool = False, output_format: Optional[weaver.formats.AnyOutputFormat] = None, page: Optional[int] = None, limit: Optional[int] = None, status: Optional[weaver.status.StatusType] = None, detail: bool = False, groups: bool = False) OperationResult [source]
Obtain a listing of Job.
See also
- Parameters
url – Instance URL if not already provided during client creation.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
output_format – Select an alternate output representation of the result body contents.
page – Paging index to list jobs.
limit – Amount of jobs to list per page.
status – Filter job listing only to matching status.
detail – Obtain detailed job descriptions.
groups – Obtain grouped representation of jobs per provider and process categories.
- Returns
Retrieved status of the job.
- status(self: str, job_reference: Optional[str], url: bool = None, show_links: bool = True, show_headers: Optional[weaver.formats.AnyOutputFormat] = False, output_format=None) OperationResult [source]
Obtain the status of a Job.
See also
- Parameters
job_reference – Either the full Job status URL or only its UUID.
url – Instance URL if not already provided during client creation.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
output_format – Select an alternate output representation of the result body contents.
- Returns
Retrieved status of the job.
- monitor(self: Ellipsis, job_reference: str, timeout: Optional[int] = None, interval: Optional[int] = None, wait_for_status: str = Status.SUCCEEDED, url: Optional[str] = None, show_links: bool = True, show_headers: bool = False, output_format: Optional[weaver.formats.AnyOutputFormat] = None) OperationResult [source]
Monitor the execution of a Job until completion.
See also
- 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.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
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(self: weaver.typedefs.ExecutionResults, outputs: weaver.typedefs.AnyHeadersContainer, out_links: str, out_dir: str, job_id) 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(self: Ellipsis, job_reference: str, out_dir: Optional[str] = None, download: bool = False, url: Optional[str] = None, show_links: bool = True, show_headers: bool = False, output_format: Optional[weaver.formats.AnyOutputFormat] = 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.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
output_format – Select an alternate output representation of the result body contents.
- Returns
Result details and local paths if downloaded.
- dismiss(self: str, job_reference: Optional[str], url: bool = None, show_links: bool = True, show_headers: Optional[weaver.formats.AnyOutputFormat] = False, output_format=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.
show_links – Indicate if
links
section should be preserved in returned result body.show_headers – Indicate if response headers should be returned in result output.
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 setup 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_process_param(parser: argparse.ArgumentParser, description: Optional[str] = None, required: bool = True) None [source]
- weaver.cli.add_job_ref_param(parser: argparse.ArgumentParser) None [source]
- weaver.cli.add_timeout_param(parser: argparse.ArgumentParser) None [source]
- weaver.cli.set_parser_sections(parser: argparse.ArgumentParser) None [source]
- 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.
- 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)[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)[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.WeaverArgumentParser(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)[source]
Parser that provides fixes for proper representation of Weaver CLI arguments.
- 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.