weaver.cli ========== .. py:module:: weaver.cli Module Contents --------------- .. py:data:: AnyOutputFormat .. py:data:: LOGGER .. py:data:: OPERATION_ARGS_TITLE :value: 'Operation Arguments' .. py:data:: OPTIONAL_ARGS_TITLE :value: 'Optional Arguments' .. py:data:: REQUIRED_ARGS_TITLE :value: 'Required Arguments' .. py:class:: 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) Data container for any :class:`WeaverClient` operation results. :param success: Success status of the operation. :param message: Detail extracted from response content if available. :param headers: Headers returned by the response for reference. :param body: Content of :term:`JSON` response or fallback in plain text. :param text: Pre-formatted text representation of :paramref:`body`. Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: success :type: Optional[bool] :value: False .. py:attribute:: message :type: Optional[str] :value: '' .. py:attribute:: headers :type: Optional[weaver.typedefs.AnyHeadersContainer] .. py:attribute:: body :type: Optional[Union[weaver.typedefs.JSON, str]] .. py:attribute:: code :type: Optional[int] :value: None .. py:property:: text :type: str .. py:method:: links(header_names: Optional[List[str]] = None) -> webob.headers.ResponseHeaders Obtain HTTP headers sorted in the result that corresponds to any link reference. :param header_names: Limit link names to be considered. By default, considered headers are ``Link``, ``Content-Location`` and ``Location``. .. py:class:: AuthHandler(identity: Optional[str] = None, password: Optional[str] = None, url: Optional[str] = None, method: weaver.typedefs.AnyRequestMethod = 'GET', headers: Optional[weaver.typedefs.AnyHeadersContainer] = None) Base class that all auth implementations derive from .. py:attribute:: url :type: Optional[str] :value: None .. py:attribute:: method :type: weaver.typedefs.AnyRequestMethod :value: 'GET' .. py:attribute:: headers :type: Optional[weaver.typedefs.AnyHeadersContainer] .. py:attribute:: identity :type: Optional[str] :value: None .. py:attribute:: password :type: Optional[str] :value: None .. py:class:: BasicAuthHandler(username: str, password: str, **kwargs: Any) 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. .. py:property:: username :type: str .. py:class:: RequestAuthHandler(identity: Optional[str] = None, password: Optional[str] = None, url: Optional[str] = None, method: weaver.typedefs.AnyRequestMethod = 'GET', headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, token: Optional[str] = None) Base class to send a request in order to retrieve an authorization token. .. py:attribute:: token :value: None .. py:property:: auth_token_name :type: str Override token name to retrieve in response authentication handler implementation. Default looks amongst common names: [auth, access_token, token] .. py:method:: auth_header(token: str) -> weaver.typedefs.AnyHeadersContainer :abstractmethod: Obtain the header definition with the provided authorization token. .. py:method:: parse_token(token: Any) -> str :staticmethod: :abstractmethod: Convert token to a form that can be included in a request header. .. py:method:: request_auth() -> Optional[str] Performs a request using authentication parameters to retrieve the authorization token. .. py:method:: response_parser(response: requests.Response) -> Optional[str] Parses a valid authentication response to extract the received authorization token. .. py:class:: BearerAuthHandler(identity: Optional[str] = None, password: Optional[str] = None, url: Optional[str] = None, method: weaver.typedefs.AnyRequestMethod = 'GET', headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, token: Optional[str] = None) Adds the ``Authorization`` header formed of the authentication bearer token from the underlying request. .. py:method:: parse_token(token: str) -> str :staticmethod: Convert token to a form that can be included in a request header. Returns the token string as is. .. py:method:: auth_header(token: str) -> weaver.typedefs.AnyHeadersContainer Obtain the header definition with the provided authorization token. .. py:class:: CookieAuthHandler(identity: Optional[str] = None, password: Optional[str] = None, url: Optional[str] = None, method: weaver.typedefs.AnyRequestMethod = 'GET', headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, token: Optional[Union[str, weaver.typedefs.CookiesType]] = None) Adds the ``Cookie`` header formed from the authentication bearer token from the underlying request. .. py:method:: parse_token(token: Union[str, weaver.typedefs.CookiesType]) -> str :staticmethod: 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. .. py:method:: auth_header(token: str) -> weaver.typedefs.AnyHeadersContainer Obtain the header definition with the provided authorization token. .. py:class:: WeaverClient(url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, **request_kwargs: Union[weaver.typedefs.AnyValueType, weaver.utils.RequestOptions]) Client that handles common HTTP requests with a `Weaver` or similar :term:`OGC API - Processes` instance. Initialize the client with predefined parameters. :param url: Instance URL to employ for each method call. Must be provided each time if not defined here. :param 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. :param request_kwargs: Additional request keyword arguments that will be passed to every request call. Only arguments prefixed by ``request_`` will be considered. For per-request specific options, parameter ``request_options`` can be used to provide a dictionary of desired configuration representing :term:`Request Options`. .. py:attribute:: monitor_timeout :value: 60 .. py:attribute:: monitor_interval :value: 5 .. py:attribute:: auth :type: AuthHandler :value: None .. py:attribute:: _url :value: None .. py:attribute:: _headers .. py:attribute:: _settings .. py:method:: _request_options_setup(**request_kwargs: Union[weaver.typedefs.AnyValueType, weaver.utils.RequestOptions]) -> weaver.utils.RequestOptionsSpecification .. py:method:: _request(method: weaver.typedefs.AnyRequestMethod, url: str, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, x_headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, request_options: Optional[weaver.utils.RequestOptionsSpecification] = None, **kwargs) -> weaver.typedefs.AnyResponseType .. py:method:: _get_url(url: Optional[str]) -> str .. py:method:: _parse_url(url) :staticmethod: .. py:method:: _parse_result(response: Union[requests.Response, OperationResult], body: Optional[weaver.typedefs.JSON] = None, message: Optional[str] = None, success: Optional[bool] = None, with_headers: bool = False, with_links: bool = True, nested_links: Optional[str] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None, content_type: Optional[weaver.formats.ContentType] = None) -> OperationResult :staticmethod: .. py:method:: _parse_deploy_body(body: Optional[Union[weaver.typedefs.JSON, str]], process_id: Optional[str]) -> OperationResult :staticmethod: .. py:method:: _parse_deploy_package(body: weaver.typedefs.JSON, cwl: Optional[Union[weaver.typedefs.CWL, str]], wps: Optional[str], process_id: Optional[str], headers: weaver.typedefs.HeadersType, settings: weaver.typedefs.SettingsType) -> OperationResult :staticmethod: .. py:method:: _parse_job_ref(job_reference: Union[weaver.typedefs.URL, weaver.typedefs.AnyUUID], url: Optional[str] = None) -> Tuple[Optional[str], Optional[str]] .. py:method:: _parse_auth_token(token: Optional[str], username: Optional[str], password: Optional[str]) -> weaver.typedefs.HeadersType :staticmethod: .. py:method:: info(url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Retrieve server information from the landing page. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: version(url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Retrieve server version. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: conformance(category: Optional[weaver.wps_restapi.constants.AnyConformanceCategory] = None, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Retrieve server conformance classes. :param category: Select the category of desired conformance item references to be returned. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: register(provider_id: str, provider_url: str, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Registers a remote :term:`Provider` using specified references. .. note:: This operation is specific to `Weaver`. It is not supported by standard :term:`OGC API - Processes`. :param provider_id: Identifier to employ for registering the new :term:`Provider`. :param provider_url: Endpoint location to register the new remote :term:`Provider`. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: unregister(provider_id: str, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Unregisters a remote :term:`Provider` using the specified identifier. .. note:: This operation is specific to `Weaver`. It is not supported by standard :term:`OGC API - Processes`. :param provider_id: Identifier to employ for unregistering the :term:`Provider`. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: deploy(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, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Deploy a new :term:`Process` with specified metadata and reference to an :term:`Application Package`. The referenced :term:`Application Package` must be one of: - :term:`CWL` body, local file or URL in :term:`JSON` or :term:`YAML` format - :term:`WPS` process URL with :term:`XML` response - :term:`WPS-REST` process URL with :term:`JSON` response - :term:`OGC API - Processes` process URL with :term:`JSON` response If the reference is resolved to be a :term:`Workflow`, all its underlying :term:`Process` steps must be available under the same URL that this client was initialized with. .. note:: This is only supported by :term:`OGC API - Processes` instances that support the `Deploy, Replace, Undeploy` (DRU) extension. .. seealso:: - :ref:`proc_op_deploy` :param process_id: Desired process identifier. Can be omitted if already provided in body contents or file. :param body: Literal :term:`JSON` contents, either using string representation of actual Python objects forming the request body, or file path/URL to :term:`YAML` or :term:`JSON` contents of the request body. Other parameters (:paramref:`process_id`, :paramref:`cwl`) can override corresponding fields within the provided body. :param cwl: Literal :term:`JSON` or :term:`YAML` contents, either using string representation of actual Python objects, or file path/URL with contents of the :term:`CWL` definition of the :term:`Application package` to be inserted into the body. :param wps: URL to an existing :term:`WPS` process (WPS-1/2 or WPS-REST/OGC-API). :param token: Authentication token for accessing private Docker registry if :term:`CWL` refers to such image. :param username: Username to form the authentication token to a private :term:`Docker` registry. :param password: Password to form the authentication token to a private :term:`Docker` registry. :param undeploy: Perform undeploy as necessary before deployment to avoid conflict with exiting :term:`Process`. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: undeploy(process_id: str, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Undeploy an existing :term:`Process`. :param process_id: Identifier of the process to undeploy. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: capabilities(url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, with_providers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None, sort: Optional[weaver.sort.Sort] = None, page: Optional[int] = None, limit: Optional[int] = None, detail: bool = False) -> OperationResult List all available :term:`Process` on the instance. .. seealso:: :ref:`proc_op_getcap` :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param with_providers: Indicate if remote providers should be listed as well along with local processes. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :param sort: Sorting field to list processes. Name must be one of the fields supported by process objects. :param page: Paging index to list processes. :param limit: Amount of processes to list per page. :param detail: Obtain detailed process descriptions. :returns: Results of the operation. .. py:attribute:: processes Alias of :meth:`capabilities` for :term:`Process` listing. .. py:method:: describe(process_id: str, provider_id: Optional[str] = None, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, schema: Optional[weaver.processes.constants.ProcessSchemaType] = ProcessSchema.OGC, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Describe the specified :term:`Process`. .. seealso:: :ref:`proc_op_describe` :param process_id: Identifier of the local or remote process to describe. :param provider_id: Identifier of the provider from which to locate a remote process to describe. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param schema: Representation schema of the returned process description. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: _get_process_url(url: str, process_id: str, provider_id: Optional[str] = None) -> str .. py:method:: package(process_id: str, provider_id: Optional[str] = None, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Retrieve the :term:`Application Package` definition of the specified :term:`Process`. .. note:: This operation is specific to `Weaver`. It is not supported by standard :term:`OGC API - Processes`. :param process_id: Identifier of the local or remote process to describe. :param provider_id: Identifier of the provider from which to locate a remote process to describe. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: _parse_inputs(inputs: Optional[Union[str, weaver.typedefs.ExecutionInputs, weaver.typedefs.CWL_IO_ValueMap]]) -> Union[OperationResult, weaver.typedefs.ExecutionInputsMap] :staticmethod: Parse multiple different representation formats and input sources into standard :term:`OGC` inputs. Schema :term:`OGC` is selected to increase compatibility coverage with potential non-`Weaver` servers only conforming to standard :term:`OGC API - Processes`. Inputs can be represented as :term:`CLI` option string arguments, file path to load contents from, or directly supported list or mapping of execution inputs definitions. .. py:method:: _upload_files(inputs: weaver.typedefs.ExecutionInputsMap, url: Optional[str] = None) -> Union[Tuple[weaver.typedefs.ExecutionInputsMap, weaver.typedefs.HeadersType], OperationResult] Replaces local file paths by references uploaded to the :term:`Vault`. .. seealso:: - Headers dictionary limitation by :mod:`requests`: https://requests.readthedocs.io/en/master/user/quickstart/#response-content - Headers formatting with multiple values must be provided by comma-separated values (:rfc:`7230#section-3.2.2`). - Multi Vault-Token parsing accomplished by :func:`weaver.vault.utils.parse_vault_token`. - More details about formats and operations related to :term:`Vault` are provided in :ref:`file_vault_token` and :ref:`vault_upload` chapters. :param inputs: Input values for submission of :term:`Process` execution. :return: Updated inputs or the result of a failing intermediate request. .. py:method:: _prepare_inputs(inputs: Optional[Union[str, weaver.typedefs.ExecutionInputs, weaver.typedefs.CWL_IO_ValueMap]] = None, url: Optional[str] = None) -> Union[Tuple[weaver.typedefs.ExecutionInputsMap, weaver.typedefs.HeadersType], OperationResult] 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). .. py:method:: _prepare_outputs(body: weaver.typedefs.JSON, output_ids: List[str], output_refs: Optional[Iterable[str]] = None, output_filter: Optional[Sequence[str]] = None) -> weaver.typedefs.JSON Performs inplace replacement or update of :term:`Job` outputs according to predefined and requested conditions. .. py:method:: execute(process_id: str, provider_id: Optional[str] = None, inputs: Optional[Union[str, weaver.typedefs.ExecutionInputs, weaver.typedefs.CWL_IO_ValueMap]] = None, pending: bool = False, monitor: bool = False, timeout: Optional[int] = None, interval: Optional[int] = None, subscribers: Optional[weaver.typedefs.JobSubscribers] = None, execute_mode: Optional[weaver.execute.AnyExecuteMode] = None, execute_return: Optional[weaver.execute.AnyExecuteReturnPreference] = None, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_type: Literal['core', 'jobs'] = 'core', request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None, output_refs: Optional[Iterable[str]] = None, output_filter: Optional[Sequence[str]] = None, output_context: Optional[str] = None) -> OperationResult Execute a :term:`Job` for the specified :term:`Process` with provided inputs. When submitting inputs with :term:`OGC API - Processes` schema, top-level ``inputs`` field is expected. Under this field, either the :term:`OGC` mapping (key-value) or listing (id,value) representations are accepted. If the top-level ``inputs`` field is not found, the alternative :term:`CWL` representation will be assumed. When submitting inputs with :term:`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 details as the ``class: File`` and ``path`` with location. .. warning:: Execution requests are accomplished *asynchronously* by default, unless unsupported by the target :term:`Process` as indicated in its description response. This offers more flexibility over servers that could decide to ignore sync/async preferences, and avoids closing/timeout connection errors of the request that could occur for long-running processes, since :term:`Job` status is pooled iteratively rather than waiting over a single long request. It also limits the amount of data transferred in the response, allows better recovery from connection interruptions, and reduces the complexity of handling different response formats as in the case of *synchronous* execution. To obtain the final :term:`Job` status as if the :term:`Process` execution was submitted synchronously (although submitted *asynchronously* to the server), provide the :paramref:`monitor` argument with ``True``. .. note:: To actually submit the execution request as *synchronous*, provide the :paramref:`execute_mode` argument with :attr:`weaver.process.execute.ExecuteMode.SYNC`. However, this mode is not guaranteed to be supported by the target :term:`Process`, and could lead to the request falling back to *asynchronous* execution. This execution mode is still subject to connection timeouts imposed by the remote server. Consider increasing :paramref:`timeout` in such case if the server allows it, or revert to *asynchronous* using the :paramref:`monitor` otherwise. .. warning:: Due to the nature of *synchronous* responses (different :term:`Media-Type` representations and contents, see :ref:`proc_exec_results` details), the client cannot guarantee proper parsing of the response .. seealso:: - :ref:`proc_exec_body`, :ref:`proc_exec_mode` and :ref:`proc_exec_results` documentation provides more details regarding the execution request parameters and their resulting responses formats. - :ref:`exec_output_location` provide additional consideration about output storage and retrieval. - :ref:`proc_op_execute_subscribers` provides definitions about :term:`Job` execution subscribers. :param process_id: Identifier of the local or remote process to execute. :param provider_id: Identifier of the provider from which to locate a remote process to execute. :param inputs: Literal :term:`JSON` or :term:`YAML` contents of the inputs submitted and inserted into the execution body, using either the :term:`OGC API - Processes` or :term:`CWL` format, or a file path/URL referring to them. :param pending: If enabled, the :term:`Job` will be created, but will not immediately start execution. The :term:`Job` will be pending execution until a following :meth:`trigger_job` is sent. When enabled, :paramref:`monitor` parameter is ignored since it is expected that no execution will occur. Also, the :paramref:`request_path` will be enforced to ``"jobs"`` since this is the only one supporting it. :param monitor: Automatically perform :term:`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. :param timeout: Monitoring timeout (seconds) if requested. :param interval: Monitoring interval (seconds) between job status polling requests. :param 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. :param execute_mode: Preferred execution mode to request from the server if supported by the :term:`Process`. :param execute_return: Preferred execution return response to request from the server if supported by the :term:`Process`. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_type: Whether to employ the :term:`OGC API - Processes` *Part 1: Core* endpoint (i.e.: ``/processes/{processID}/execution``) or the :term:`OGC API - Processes` *Part 4: Job Management* endpoint (i.e.: ``/jobs``) to submit the :term:`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"`` if :paramref:`pending` is requested. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :param 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. :param output_filter: Indicates a list of outputs to omit from the results. If unspecified (default), all outputs are returned. :param output_context: Specify an output context for which the `Weaver` instance should attempt storing the :term:`Job` results under the nested location of its configured :term:`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. .. py:method:: trigger_job(job_reference: Union[weaver.typedefs.URL, weaver.typedefs.AnyUUID], url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Trigger a *pending* :term:`Job` execution. To submit a *pending* :term:`Job`, see the ``pending`` parameter of :meth:`execute`. This call only applies to a :term:`Job` that is :attr:`Status.CREATED`. Otherwise, an error should be returned by the :term:`API` since the operation doesn't apply for an already submitted, running or completed :term:`Job`. Once triggered, the :meth:`monitor` operation should be used to track the :term:`Job` progress until completion. :param job_reference: Either the full :term:`Job` status URL or only its UUID. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :return: Result of the :term:`Job` trigger operation. .. py:method:: update_job(job_reference: Union[weaver.typedefs.URL, weaver.typedefs.AnyUUID], title: Union[Type[weaver.utils.null], Optional[str]] = null, inputs: Optional[Union[str, weaver.typedefs.ExecutionInputs, weaver.typedefs.CWL_IO_ValueMap]] = None, subscribers: Optional[weaver.typedefs.JobSubscribers] = None, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None, output_refs: Optional[Iterable[str]] = None, output_filter: Optional[Sequence[str]] = None, output_context: Optional[str] = None) -> OperationResult Trigger a *pending* :term:`Job` execution. To submit a *pending* :term:`Job`, see the ``pending`` parameter of :meth:`execute`. This call only applies to a :term:`Job` that is :attr:`Status.CREATED`. Otherwise, an error should be returned by the :term:`API` since the operation doesn't apply for an already submitted, running or completed :term:`Job`. Once triggered, the :meth:`monitor` operation should be used to track the :term:`Job` progress until completion. To evaluate the current state of the inputs of a *pending* :term:`Job`, it is recommended to employ the :meth:`inputs` operation. This can be used in unison with :meth:`update_job` to iteratively adjust the :term:`Job` configuration until it is ready for :meth:`trigger_job` execution. :param job_reference: Either the full :term:`Job` status URL or only its UUID. :param title: Title value to update. Note that an explicit :class:`None` unsets the title. :param inputs: Literal :term:`JSON` or :term:`YAML` contents of the inputs submitted and inserted into the execution body, using either the :term:`OGC API - Processes` or :term:`CWL` format, or a file path/URL referring to them. :param 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. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :param 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. :param output_filter: Indicates a list of outputs to omit from the results. If unspecified (default), all outputs are returned. :param output_context: Specify an output context for which the `Weaver` instance should attempt storing the :term:`Job` results under the nested location of its configured :term:`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. :return: Result of the :term:`Job` update operation. .. py:method:: upload(file_path: str, content_type: Optional[str] = None, content_encoding: Optional[weaver.formats.ContentEncoding] = None, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Upload a local file to the :term:`Vault`. .. note:: Feature only available for `Weaver` instances. Not available for standard :term:`OGC API - Processes`. .. seealso:: More details about formats and operations related to :term:`Vault` are provided in :ref:`file_vault_token` and :ref:`vault_upload` chapters. :param file_path: Location of the file to be uploaded. :param 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. :param content_encoding: Specify the Content-Encoding of the file. For text use ``utf-8`` or leave ``None``. For binary use ``base64`` or ``binary``. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Results of the operation. .. py:method:: jobs(url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None, sort: Optional[weaver.sort.Sort] = None, page: Optional[int] = None, limit: Optional[int] = None, status: Optional[Union[weaver.status.AnyStatusSearch, List[weaver.status.AnyStatusSearch]]] = None, detail: bool = False, groups: bool = False, process: Optional[str] = None, provider: Optional[str] = None, tags: Optional[Union[str, List[str]]] = None) -> OperationResult Obtain a listing of :term:`Job`. .. seealso:: :ref:`proc_op_status` :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :param sort: Sorting field to list jobs. Name must be one of the fields supported by job objects. :param page: Paging index to list jobs. :param limit: Amount of jobs to list per page. :param status: Filter job listing only to matching status. If multiple are provided, must match one of them. :param detail: Obtain detailed job descriptions. :param groups: Obtain grouped representation of jobs per provider and process categories. :param process: Obtain jobs executed only by matching :term:`Process`. :param provider: Obtain jobs only matching remote :term:`Provider`. :param tags: Obtain jobs filtered by matching tags. Jobs must match all tags simultaneously, not one of them. :returns: Retrieved status of the job. .. py:method:: status(job_reference: Union[weaver.typedefs.URL, weaver.typedefs.AnyUUID], url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Obtain the status of a :term:`Job`. .. seealso:: :ref:`proc_op_status` :param job_reference: Either the full :term:`Job` status URL or only its UUID. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Retrieved status of the :term:`Job`. .. py:method:: _job_info(x_path: str, job_reference: Union[weaver.typedefs.URL, weaver.typedefs.AnyUUID], url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Obtain the information from a :term:`Job`. The :term:`Job` must be in the expected status to retrieve relevant information. .. seealso:: :ref:`proc_op_status` :param job_reference: Either the full :term:`Job` status URL or only its UUID. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Retrieved information from the :term:`Job`. .. py:method:: inputs(*args, **kwargs) .. py:method:: logs(*args, **kwargs) .. py:method:: exceptions(*args, **kwargs) .. py:attribute:: errors .. py:method:: statistics(*args, **kwargs) .. py:attribute:: stats .. py:method:: provenance(job_reference: Union[weaver.typedefs.URL, weaver.typedefs.AnyUUID], prov: Optional[weaver.provenance.ProvenancePathType] = None, prov_run_id: Optional[weaver.typedefs.AnyUUID] = None, prov_format: Optional[weaver.provenance.ProvenanceFormat] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, **kwargs) -> OperationResult Obtain the :term:`Provenance` metadata from a successful :term:`Job` execution. The :term:`Job` must be in the expected status to retrieve relevant information. .. seealso:: - :ref:`proc_op_status` - :ref:`proc_op_job_prov` :param job_reference: Either the full :term:`Job` status URL or only its UUID. :param prov: Type of :term:`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 :term:`API` endpoints (see :class:`ProvenancePathType`). Can be combined in certain cases with a :paramref:`run_id` to obtain only the metadata of a nested step within a :term:`Workflow` execution. If omitted, returns the main :term:`Provenance` metadata representation as per the requested :paramref:`prov_format` (see :class:`ProvenanceFormat`). :param prov_run_id: Specific run (i.e.: a nested :term:`Workflow` step) for which to retrieve :term:`Provenance` metadata. Applicable IDs will typically correspond to the underlying :term:`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. :param prov_format: Desired :term:`Provenance` metadata representation (see :class:`ProvenanceFormat`). Applicable only when retrieving the ``PROV`` details (i.e.: :paramref:`prov` must be ``None`` or ``/prov``). Ignored otherwise. Can be combined with :paramref:`output_format` to convert the representation into semantically equivalent representations. For example, :attr:`ProvenanceFormat.PROV_JSON` could be converted into the corresponding :term:`YAML` representation using :attr:`OutputFormat.YAML`. However, this is limited only to directly mappable representations (i.e.: :term:`JSON`, :term:`YAML`, :term:`XML`). :param output_format: Select an alternate output representation of the result body contents. See also :paramref:`prov_format` for even more format combinations specific to :term:`Provenance` metadata. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param 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 :term:`Job`. .. py:attribute:: prov .. py:method:: monitor(job_reference: str, timeout: Optional[int] = None, interval: Optional[int] = None, wait_for_status: str = Status.SUCCESSFUL, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Monitor the execution of a :term:`Job` until completion. .. seealso:: :ref:`proc_op_monitor` :param job_reference: Either the full :term:`Job` status URL or only its UUID. :param timeout: timeout (seconds) of maximum wait time for monitoring if completion is not reached. :param interval: wait interval (seconds) between polling monitor requests. :param wait_for_status: monitor until the requested status is reached (default: job failed or succeeded). :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :return: Result of the successful or failed job, or timeout of monitoring process. .. py:method:: _download_references(outputs: weaver.typedefs.ExecutionResults, out_links: weaver.typedefs.AnyHeadersContainer, out_dir: str, job_id: str, auth: Optional[requests.auth.AuthBase] = None) -> weaver.typedefs.ExecutionResults Download file references from results response contents and link headers. Downloaded files extend the results contents with ``path`` and ``source`` 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. .. py:method:: results(job_reference: str, out_dir: Optional[str] = None, download: bool = False, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None, output_links: Optional[Sequence[str]] = None) -> OperationResult Obtain the results of a successful :term:`Job` execution. :param job_reference: Either the full :term:`Job` status URL or only its UUID. :param out_dir: Output directory where to store downloaded files if requested (default: CURDIR/JobID/). :param download: Download any file reference found within results (CAUTION: could transfer lots of data!). :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :param 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 of ``Links`` in responses, and output IDs could have conflicting ``rel`` names with other indicative links. :returns: Result details and local paths if downloaded. .. py:method:: dismiss(job_reference: str, url: Optional[str] = None, auth: Optional[requests.auth.AuthBase] = None, headers: Optional[weaver.typedefs.AnyHeadersContainer] = None, with_links: bool = True, with_headers: bool = False, request_timeout: Optional[int] = None, request_retries: Optional[int] = None, output_format: Optional[weaver.formats.AnyOutputFormat] = None) -> OperationResult Dismiss pending or running :term:`Job`, or clear result artifacts from a completed :term:`Job`. :param job_reference: Either the full :term:`Job` status URL or only its UUID. :param url: Instance URL if not already provided during client creation. :param auth: Instance authentication handler if not already created during client creation. Should perform required adjustments to request to allow access control of protected contents. :param headers: Additional headers to employ when sending request. Note that this can break functionalities if expected headers are overridden. Use with care. :param with_links: Indicate if ``links`` section should be preserved in returned result body. :param with_headers: Indicate if response headers should be returned in result output. :param request_timeout: Maximum timeout duration (seconds) to wait for a response when performing HTTP requests. :param request_retries: Amount of attempt to retry HTTP requests in case of failure. :param output_format: Select an alternate output representation of the result body contents. :returns: Obtained result from the operation. .. py:function:: setup_logger_from_options(logger: logging.Logger, args: argparse.Namespace) -> None 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. .. py:function:: make_logging_options(parser: argparse.ArgumentParser) -> None Defines argument parser options for logging operations. .. py:function:: add_url_param(parser: argparse.ArgumentParser, required: bool = True) -> None .. py:function:: add_shared_options(parser: argparse.ArgumentParser) -> None .. py:function:: add_listing_options(parser: argparse.ArgumentParser, item: str) -> None .. py:function:: parse_auth(kwargs: Dict[str, Union[Type[AuthHandler], Type[requests.auth.AuthBase], str, None]]) -> Optional[AuthHandler] Parses arguments that can define an authentication handler and remove them from dictionary for following calls. .. py:function:: add_provider_param(parser: argparse.ArgumentParser, description: Optional[str] = None, required: bool = True) -> None .. py:function:: add_process_param(parser: argparse.ArgumentParser, description: Optional[str] = None, required: bool = True) -> None .. py:function:: add_job_ref_param(parser: argparse.ArgumentParser) -> None .. py:function:: add_job_title_param(parser: argparse.ArgumentParser) -> None .. py:function:: add_job_exec_param(parser: argparse.ArgumentParser) -> None .. py:function:: add_timeout_param(parser: argparse.ArgumentParser) -> None .. py:function:: add_provenance_params(parser: argparse.ArgumentParser) -> None .. py:function:: check_compatible_prov_formats(ns: argparse.Namespace) -> Optional[str] 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. .. py:class:: SubscriberAction(option_strings: List[str], dest: str = None, **kwargs: Any) 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 a ``dest="."`` parameter that will map the ``subscriber`` value under a dictionary ``holder`` that will be passed to the :class:`argparse.Namespace`. .. py:method:: validate(option: str, value: Any) -> None .. py:function:: add_subscribers_params(parser: argparse.ArgumentParser) -> None .. py:function:: set_parser_sections(parser: argparse.ArgumentParser) -> None .. py:class:: ValidateAuthHandlerAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None) Action that will validate that the input argument references an authentication handler that can be resolved. .. py:method:: validate(auth_handler_ref: Optional[str]) -> Optional[Union[Type[AuthHandler], Type[requests.auth.AuthBase]]] :staticmethod: Validate the referenced authentication handler implementation. .. py:class:: ValidateMethodAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None) Action that will validate that the input argument one of the accepted HTTP methods. .. py:attribute:: methods :value: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE'] .. py:class:: ValidateSettingAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None) Action that will validate that the input argument is a correctly formed as setting/value pair. .. code-block:: text setting_name=setting_value .. py:class:: ValidateHeaderAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None) 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: .. code-block:: text Header-Name: Header-Value .. py:class:: ValidateNonZeroPositiveNumberAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None) Action that will validate that the input argument is a positive number greater than zero. .. py:class:: ParagraphFormatter(prog, indent_increment=2, max_help_position=24, width=None) 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. .. py:property:: help_mode .. py:method:: format_help() -> str .. py:method:: _format_usage(*args, **kwargs) .. py:method:: _format_action(action: argparse.Action) -> str 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. .. py:class:: 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) Patch incorrectly handled mutually exclusive groups sections in subparsers. .. seealso:: - https://bugs.python.org/issue43259 - https://bugs.python.org/issue16807 .. py:method:: _add_container_actions(container) .. py:class:: 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) 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 if ``required`` is defined. Help string correctly considers this flag and doesn't place those arguments in brackets (``[--]``). .. py:method:: _add_action(action) .. py:class:: WeaverSubParserAction(option_strings, prog, parser_class, dest=SUPPRESS, required=False, help=None, metavar=None) Parser that provides fixes for proper representation of `Weaver` :term:`CLI` operations. .. py:method:: add_parser(*args, **kwargs) .. py:class:: WeaverArgumentParser(*args: Any, **kwargs: Any) Parser that provides fixes for proper representation of `Weaver` :term:`CLI` arguments. .. py:attribute:: _help_mode :value: False .. py:attribute:: _conditional_groups :type: Set[ConditionalGroup] .. py:attribute:: _formatters :type: Set[PostHelpFormatter] .. py:attribute:: _rules :type: Set[ArgumentParserRule] .. py:method:: add_subparsers(*args, **kwargs) .. py:property:: help_mode Option enabled only during help formatting to generate different conditional evaluations. .. py:method:: add_help_conditional(container: argparse._ActionsContainer, help_required: bool = True, use_required: bool = False) -> argparse._ActionsContainer .. py:method:: add_formatter(formatter: Callable[[str], str]) -> None Define a POST-help formatter. .. py:method:: _get_formatter() -> argparse.HelpFormatter .. py:method:: format_help() -> str .. py:method:: add_rule(rule: ArgumentParserRuleCheck, failure: Optional[str] = None) -> None .. py:method:: parse_known_args(args: Optional[Sequence[str]] = None, namespace: Optional[argparse.Namespace] = None) -> Tuple[argparse.Namespace, Sequence[str]] Parse argument actions with handling of additional rules if any were defined. .. note:: It is important to derive and call :meth:`parse_known_args` rather than :meth:`parse_args` to ensure nested subparsers rules validation can also be invoked. .. py:function:: make_parser() -> argparse.ArgumentParser Generate the :term:`CLI` parser. .. note:: Instead of employing :class:`argparse.ArgumentParser` instances returned by :meth:`argparse._SubParsersAction.add_parser`, distinct :class:`argparse.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. .. py:function:: main(*args: str) -> int