weaver.execute ============== .. py:module:: weaver.execute Module Contents --------------- .. py:data:: ExecuteModeAutoType .. py:data:: LOGGER .. py:class:: ExecuteMode Constants container that provides similar functionalities to :class:`ExtendedEnum` without explicit Enum membership. .. py:attribute:: AUTO :type: ExecuteModeAutoType :value: 'auto' .. py:attribute:: ASYNC :type: ExecuteModeAsyncType :value: 'async' .. py:attribute:: SYNC :type: ExecuteModeSyncType :value: 'sync' .. py:class:: ExecuteControlOption Constants container that provides similar functionalities to :class:`ExtendedEnum` without explicit Enum membership. .. py:attribute:: ASYNC :type: ExecuteControlOptionAsyncType :value: 'async-execute' .. py:attribute:: SYNC :type: ExecuteControlOptionSyncType :value: 'sync-execute' .. py:method:: values() -> List[AnyExecuteControlOption] :classmethod: Return default control options in specific order according to preferred modes for execution by `Weaver`. .. py:method:: from_mode(mode: Optional[AnyExecuteMode]) -> Optional[ExecuteControlOption] :classmethod: .. py:class:: ExecuteReturnPreference Constants container that provides similar functionalities to :class:`ExtendedEnum` without explicit Enum membership. .. py:attribute:: MINIMAL :type: ExecuteReturnPreferenceMinimalType :value: 'minimal' .. py:attribute:: REPRESENTATION :type: ExecuteReturnPreferenceRepresentationType :value: 'representation' .. py:class:: ExecuteResponse Constants container that provides similar functionalities to :class:`ExtendedEnum` without explicit Enum membership. .. py:attribute:: RAW :type: ExecuteResponseRawType :value: 'raw' .. py:attribute:: DOCUMENT :type: ExecuteResponseDocumentType :value: 'document' .. py:class:: ExecuteTransmissionMode Constants container that provides similar functionalities to :class:`ExtendedEnum` without explicit Enum membership. .. py:attribute:: VALUE :type: ExecuteTransmissionModeValueType :value: 'value' .. py:attribute:: REFERENCE :type: ExecuteTransmissionModeReferenceType :value: 'reference' .. py:class:: ExecuteCollectionFormat Constants container that provides similar functionalities to :class:`ExtendedEnum` without explicit Enum membership. .. py:attribute:: STAC :type: ExecuteCollectionFormatType_STAC :value: 'stac-collection' .. py:attribute:: STAC_ITEMS :type: ExecuteCollectionFormatType_STAC_ITEMS :value: 'stac-items' .. py:attribute:: OGC_COVERAGE :type: ExecuteCollectionFormatType_OGC_COVERAGE :value: 'ogc-coverage-collection' .. py:attribute:: OGC_FEATURES :type: ExecuteCollectionFormatType_OGC_FEATURES :value: 'ogc-features-collection' .. py:attribute:: OGC_MAP :type: ExecuteCollectionFormatType_OGC_MAP :value: 'ogc-map-collection' .. py:attribute:: GEOJSON :type: ExecuteCollectionFormatType_GEOJSON :value: 'geojson-feature-collection' .. py:function:: parse_prefer_header_return(headers: weaver.typedefs.AnyHeadersContainer) -> Optional[AnyExecuteReturnPreference] Get the return preference if specified. .. py:function:: parse_prefer_header_execute_mode(header_container: weaver.typedefs.AnyHeadersContainer, supported_modes: Optional[List[AnyExecuteControlOption]] = None, wait_max: int = 10, return_auto: bool = False) -> Tuple[AnyExecuteMode, Optional[int], weaver.typedefs.HeadersType] Obtain execution preference if provided in request headers. .. seealso:: - :term:`OGC API - Processes`: Core, Execution mode < https://docs.ogc.org/is/18-062r2/18-062r2.html#sc_execution_mode>`_. This defines all conditions how to handle ``Prefer`` against applicable :term:`Process` description. - :rfc:`7240#section-4.1` HTTP Prefer header ``respond-async`` .. seealso:: If ``Prefer`` format is valid, but server decides it cannot be respected, it can be transparently ignored (:rfc:`7240#section-2`). The server must respond with ``Preference-Applied`` indicating preserved preferences it decided to respect. :param header_container: Request headers to retrieve preference, if any available. :param supported_modes: Execute modes that are permitted for the operation that received the ``Prefer`` header. Resolved mode will respect this constraint following specification requirements of :term:`OGC API - Processes`. :param wait_max: Maximum wait time enforced by the server. If requested wait time is greater, ``wait`` preference will not be applied and will fall back to asynchronous response. :param return_auto: If the resolution ends up being an "auto" selection, the auto-resolved mode, wait-time, etc. are returned by default. Using this option, the "auto" mode will be explicitly returned instead, allowing a mixture of execution mode to be "auto" handled at another time. This is mostly for reporting purposes. :return: Tuple of resolved execution mode, wait time if specified, and header of applied preferences if possible. Maximum wait time indicates duration until synchronous response should fall back to asynchronous response. :raises HTTPBadRequest: If contents of ``Prefer`` are not valid. .. py:function:: rebuild_prefer_header(job: weaver.datatype.Job) -> Optional[str] Rebuilds the expected ``Prefer`` header value from :term:`Job` parameters. .. py:function:: update_preference_applied_return_header(job: weaver.datatype.Job, request_headers: Optional[weaver.typedefs.AnyHeadersContainer], response_headers: Optional[weaver.typedefs.PreservedHeadersType]) -> weaver.typedefs.PreservedHeadersType Updates the ``Preference-Applied`` header according to available information. :param job: Job where the desired return preference has be resolved. :param request_headers: Original request headers, to look for any ``Prefer: return``. :param response_headers: Already generated response headers, to extend ``Preference-Applied`` header as needed. :return: Updated response headers with any resolved return preference. .. py:function:: resolve_execution_parameters(job_control_options: List[ExecuteControlOption], execute_headers: weaver.typedefs.AnyHeadersContainer, execute_mode: Optional[AnyExecuteMode] = None, execute_return: Optional[AnyExecuteReturnPreference] = None, execute_max_wait: Optional[int] = None) -> Tuple[AnyExecuteMode, AnyExecuteResponse, weaver.typedefs.AnyHeadersContainer] Resolve execution parameters from provided :term:`Job` control options and :term:`Process` execution headers. The execution mode override, if provided, takes precedence over any header preference. If the :term:`Process` only supports a single execution mode, it is enforced regardless of any preference. If that option mismatches the override, an exception is raised. If no override is provided, or no preference is specified in headers, the asynchronous mode will be employed in case of multiple supported modes. .. seealso:: :ref:`proc_exec_body`, :ref:`proc_exec_mode` and :ref:`proc_exec_results` provide combination matrices and details on how execution parameters interact and affect the execution and response strategies. .. note:: Returned parameters include multiple "equivalent" or "redundant" variants to handle both :term:`OGC API - Processes` ``v1`` and ``v2``, and various combinations the servers could implement. :param job_control_options: The allowed execution methods that the :term:`Process` supports. :param execute_headers: Any preestablished headers that could hint a preferred execution mode. :param execute_mode: Explicit execution mode to enforce, if any. :param execute_return: Explicit return preference to enforce, if any. :param execute_max_wait: Maximum wait time for synchronous execution, as applicable. :return: Resolved execution mode and corresponding headers to apply. :raises ProcessInvalidParameter: If the requested execution mode does not respect the supported ones.