magpie.api.generic ================== .. py:module:: magpie.api.generic Attributes ---------- .. autoapisummary:: magpie.api.generic.CONTENT_TYPE_ANY magpie.api.generic.CONTENT_TYPE_HTML magpie.api.generic.CONTENT_TYPE_JSON magpie.api.generic.FORMAT_TYPE_MAPPING magpie.api.generic.SUPPORTED_ACCEPT_TYPES magpie.api.generic.LOGGER Classes ------- .. autoapisummary:: magpie.api.generic.RemoveSlashNotFoundViewFactory Functions --------- .. autoapisummary:: magpie.api.generic.get_principals magpie.api.generic.get_authenticate_headers magpie.api.generic.get_header magpie.api.generic.get_logger magpie.api.generic.is_magpie_ui_path 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:function:: get_principals(request: pyramid.request.Request) -> List[magpie.typedefs.AnyAccessPrincipalType] Obtains the list of effective principals according to detected request session user. .. py:data:: CONTENT_TYPE_ANY :value: '*/*' .. py:data:: CONTENT_TYPE_HTML :value: 'text/html' .. py:data:: CONTENT_TYPE_JSON :value: 'application/json' .. py:data:: FORMAT_TYPE_MAPPING .. py:data:: SUPPORTED_ACCEPT_TYPES .. py:function:: get_authenticate_headers(request: pyramid.request.Request, error_type: magpie.typedefs.Str = 'invalid_token') -> Optional[magpie.typedefs.HeadersType] Obtains all required headers by 401 responses based on executed :paramref:`request`. :param request: request that was sent to attempt authentication or access which must respond with Unauthorized. :param error_type: Additional detail of the cause of error. Must be one of (invalid_request, invalid_token, insufficient_scope). .. 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_magpie_ui_path(request: pyramid.request.Request) -> bool Determines if the request path corresponds to any Magpie UI location. .. 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: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.