weaver.execute
==============

.. py:module:: weaver.execute








Module Contents
---------------

.. py:data:: ExecutionModeAutoType

.. py:data:: LOGGER

.. py:class:: ExecuteMode



   Constants container that provides similar functionalities to :class:`ExtendedEnum` without explicit Enum membership.


   .. py:attribute:: AUTO
      :type:  ExecutionModeAutoType
      :value: 'auto'



   .. py:attribute:: ASYNC
      :type:  ExecutionModeAsyncType
      :value: 'async'



   .. py:attribute:: SYNC
      :type:  ExecutionModeSyncType
      :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.AnyHeadersContainer]) -> weaver.typedefs.AnyHeadersContainer

   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.