magpie.owsrequest
=================

.. py:module:: magpie.owsrequest

.. autoapi-nested-parse::

   The OWSRequest is based on pywps code:

   * https://github.com/geopython/pywps/tree/pywps-3.2/pywps/Parser
   * https://github.com/geopython/pywps/blob/master/pywps/app/WPSRequest.py



Attributes
----------

.. autoapisummary::

   magpie.owsrequest.CONTENT_TYPE_FORM
   magpie.owsrequest.CONTENT_TYPE_JSON
   magpie.owsrequest.CONTENT_TYPE_PLAIN
   magpie.owsrequest.LOGGER


Classes
-------

.. autoapisummary::

   magpie.owsrequest.OWSParser
   magpie.owsrequest.OWSGetParser
   magpie.owsrequest.OWSPostParser
   magpie.owsrequest.MultiFormatParser


Functions
---------

.. autoapisummary::

   magpie.owsrequest.get_multiformat_body
   magpie.owsrequest.get_header
   magpie.owsrequest.get_logger
   magpie.owsrequest.is_json_body
   magpie.owsrequest.ows_parser_factory


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

.. py:function:: get_multiformat_body(request: pyramid.request.Request, key: magpie.typedefs.Str, default: Optional[Any] = None) -> Any

   Obtains the value of :paramref:`key` element from the request body according to specified `Content-Type` header.

   .. seealso::
       - :func:`get_multiformat_body_checked`
       - :func:`get_permission_multiformat_body_checked`
       - :func:`get_value_multiformat_body_checked`


.. py:data:: CONTENT_TYPE_FORM
   :value: 'application/x-www-form-urlencoded'


.. py:data:: CONTENT_TYPE_JSON
   :value: 'application/json'


.. py:data:: CONTENT_TYPE_PLAIN
   :value: 'text/plain'


.. py:function:: get_header(header_name: magpie.typedefs.Str, header_container: magpie.typedefs.AnyHeadersType, default: (Optional[magpie.typedefs.Str], Optional[Union[magpie.typedefs.Str, List[magpie.typedefs.Str]]], bool) = None, split: Optional[Union[magpie.typedefs.Str, List[magpie.typedefs.Str]]] = None, multi: bool = False, pop: bool = False) -> Optional[Union[magpie.typedefs.Str, List[magpie.typedefs.Str]]]

   Retrieves ``header_name`` by fuzzy match (independently of upper/lower-case and underscore/dash) from various
   framework implementations of ``Headers``.

   If ``split`` is specified, the matched ``header_name`` is first split with it and the first item is returned.
   This allows to parse complex headers (e.g.: ``text/plain; charset=UTF-8`` to ``text/plain`` with ``split=';'``).

   :param header_name: Header to find.
   :param header_container: Where to look for `header_name`.
   :param default: Value to returned if `header_container` is invalid or `header_name` could not be found.
   :param split: Character(s) to use to split the *found* `header_name`.
   :param multi: Return extracted header as array of multiple values or return a single value on fist match.
   :param pop: Remove the header from the container if found.
   :returns: Found header value(s) if applicable.


.. py:function:: get_logger(name: magpie.typedefs.Str, level: Optional[int] = None, force_stdout: bool = None, message_format: Optional[magpie.typedefs.Str] = None, datetime_format: Optional[magpie.typedefs.Str] = None) -> logging.Logger

   Immediately sets the logger level to avoid duplicate log outputs from the `root logger` and `this logger` when
   `level` is ``logging.NOTSET``.


.. py:function:: is_json_body(body: Any, return_body: bool = False) -> bool

.. py:data:: LOGGER

.. py:function:: ows_parser_factory(request: pyramid.request.Request) -> OWSParser

   Retrieve the appropriate :class:`OWSParser` parser using the ``Content-Type`` header.

   If the ``Content-Type`` header is missing or ``text/plain``, and the request has a body,
   try to parse the body as JSON and set the content-type to ``application/json`` if successful.

   Handle XML-like ``Content-Type`` headers such as ``application/x-www-form-urlencoded`` whenever applicable.

   Otherwise, use the basic :class:`OWSGetParser` or :class:`OWSPostParser` according to the presence of a body.
   These provide minimal parsing to handle most typical `OGC Web Services` (:term:`OWS`) request parameters.


.. py:class:: OWSParser(request)

   Bases: :py:obj:`object`


   .. py:method:: parse(param_list)

      Parses the initialized :attr:`request` to populate :attr:`params` retrieved from the parser.

      Once this method has been called, all expected parameters are guaranteed to exist within :attr`params`.
      Missing query parameters from the :attr:`request` will be set to ``None``.
      All query parameter names will be normalized to *lower* characters for easier retrieval.

      :param param_list: all known query parameters to the service.



   .. py:method:: _get_param_value(param)
      :abstractmethod:



.. py:class:: OWSGetParser(request)

   Bases: :py:obj:`OWSParser`


   Basically a case-insensitive query string parser.


   .. py:method:: _request_params()


   .. py:method:: _get_param_value(param)


.. py:class:: OWSPostParser(request)

   Bases: :py:obj:`OWSParser`


   .. py:method:: _get_param_value(param)


.. py:class:: MultiFormatParser(request)

   Bases: :py:obj:`OWSParser`


   .. py:method:: _get_param_value(param)