magpie.api.generic
==================

.. py:module:: magpie.api.generic


Attributes
----------

.. autoapisummary::

   magpie.api.generic.LOGGER


Classes
-------

.. autoapisummary::

   magpie.api.generic.RemoveSlashNotFoundViewFactory


Functions
---------

.. autoapisummary::

   magpie.api.generic.internal_server_error
   magpie.api.generic.not_found_or_method_not_allowed
   magpie.api.generic.unauthorized_or_forbidden
   magpie.api.generic.guess_target_format
   magpie.api.generic.validate_accept_header_tween
   magpie.api.generic.apply_response_format_tween
   magpie.api.generic.get_exception_info
   magpie.api.generic.get_request_info


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

.. py:data:: LOGGER

.. py:class:: RemoveSlashNotFoundViewFactory(notfound_view=None)

   Bases: :py:obj:`object`


   Utility that will try to resolve a path without appended slash if one was provided.


   .. py:attribute:: notfound_view
      :value: None



   .. py:method:: __call__(request)


.. py:function:: internal_server_error(request: pyramid.request.Request) -> pyramid.httpexceptions.HTTPException

   Overrides default HTTP.


.. py:function:: not_found_or_method_not_allowed(request: pyramid.request.Request) -> pyramid.httpexceptions.HTTPException

   Overrides the default ``HTTPNotFound`` [404] by appropriate ``HTTPMethodNotAllowed`` [405] when applicable.

   Not found response can correspond to underlying process operation not finding a required item, or a completely
   unknown route (path did not match any existing API definition).
   Method not allowed is more specific to the case where the path matches an existing API route, but the specific
   request method (GET, POST, etc.) is not allowed on this path.

   Without this fix, both situations return [404] regardless.


.. py:function:: unauthorized_or_forbidden(request: pyramid.request.Request) -> pyramid.httpexceptions.HTTPException

   Overrides the default HTTP ``Forbidden [403]`` by appropriate ``Unauthorized [401]`` when applicable.

   Unauthorized response is for restricted user access according to missing credentials and/or authorization headers.
   Forbidden response is for operation refused by the underlying process operations or due to insufficient permissions.

   Without this fix, both situations return ``Forbidden [403]`` regardless.

   .. seealso::
       - http://www.restapitutorial.com/httpstatuscodes.html

   In case the request references to `Magpie UI` route, it is redirected to
   :meth:`magpie.ui.home.HomeViews.error_view` for it to handle and display the error accordingly.


.. py:function:: guess_target_format(request: pyramid.request.Request) -> Tuple[magpie.typedefs.Str, bool]

   Guess the best applicable response ``Content-Type`` header according to request ``Accept`` header and ``format``
   query, or defaulting to :py:data:`CONTENT_TYPE_JSON`.

   :returns: tuple of matched MIME-type and where it was found (``True``: header, ``False``: query)


.. py:function:: validate_accept_header_tween(handler: Callable[[pyramid.request.Request], pyramid.response.Response], registry: pyramid.registry.Registry) -> Callable[[pyramid.request.Request], pyramid.response.Response]

   Tween that validates that the specified request ``Accept`` header or ``format`` query (if any) is supported.

   Supported values are defined by :py:data:`SUPPORTED_ACCEPT_TYPES` and for the given context of API or UI.

   :raises HTTPNotAcceptable: if desired ``Accept`` or ``format`` specifier of content-type is not supported.


.. py:function:: apply_response_format_tween(handler: Callable[[pyramid.request.Request], pyramid.httpexceptions.HTTPException], registry: pyramid.registry.Registry) -> Callable[[pyramid.request.Request], pyramid.response.Response]

   Tween that applies the response ``Content-Type`` according to the requested ``Accept`` header or ``format`` query.

   The target ``Content-Type`` is expected to have been validated by :func:`validate_accept_header_tween` beforehand
   to handle not-acceptable errors. If an invalid format is detected at this stage, JSON is used by default.
   This can be the case for example for :func:`validate_accept_header_tween` itself that raises the error about
   the invalid ``Accept`` header or ``format`` query, but detects these inadequate parameters from incoming request.

   The tween also ensures that additional request metadata extracted from :func:`get_request_info` is applied to
   the response body if not already provided by a previous operation.


.. py:function:: get_exception_info(response: Union[pyramid.httpexceptions.HTTPException, pyramid.request.Request, pyramid.response.Response], content: Optional[magpie.typedefs.JSON] = None, exception_details: bool = False) -> magpie.typedefs.JSON

   Obtains additional exception content details about the :paramref:`response` according to available information.


.. py:function:: get_request_info(request: Union[pyramid.request.Request, pyramid.httpexceptions.HTTPException], default_message: Optional[magpie.typedefs.Str] = None, exception_details: bool = False) -> magpie.typedefs.JSON

   Obtains additional content details about the :paramref:`request` according to available information.