magpie.api.generic

Attributes

CONTENT_TYPE_ANY
CONTENT_TYPE_HTML
CONTENT_TYPE_JSON
FORMAT_TYPE_MAPPING
SUPPORTED_ACCEPT_TYPES
LOGGER

Classes

RemoveSlashNotFoundViewFactory

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

Functions

get_principals(...)	Obtains the list of effective principals according to detected request session user.
get_authenticate_headers(...)	Obtains all required headers by 401 responses based on executed request.
get_header(= None, split, ...)	Retrieves header_name by fuzzy match (independently of upper/lower-case and underscore/dash) from various
get_logger(→ logging.Logger)	Immediately sets the logger level to avoid duplicate log outputs from the root logger and this logger when
is_magpie_ui_path(→ bool)	Determines if the request path corresponds to any Magpie UI location.
internal_server_error(...)	Overrides default HTTP.
not_found_or_method_not_allowed(...)	Overrides the default HTTPNotFound [404] by appropriate HTTPMethodNotAllowed [405] when applicable.
unauthorized_or_forbidden(...)	Overrides the default HTTP Forbidden [403] by appropriate Unauthorized [401] when applicable.
guess_target_format(→ Tuple[magpie.typedefs.Str, bool])	Guess the best applicable response Content-Type header according to request Accept header and format
validate_accept_header_tween(...)	Tween that validates that the specified request Accept header or format query (if any) is supported.
apply_response_format_tween(...)	Tween that applies the response Content-Type according to the requested Accept header or format query.
get_exception_info(→ magpie.typedefs.JSON)	Obtains additional exception content details about the response according to available information.
get_request_info(→ magpie.typedefs.JSON)	Obtains additional content details about the request according to available information.

Module Contents

magpie.api.generic.get_principals(request: pyramid.request.Request) → List[magpie.typedefs.AnyAccessPrincipalType]

Obtains the list of effective principals according to detected request session user.

magpie.api.generic.CONTENT_TYPE_ANY = '*/*'

magpie.api.generic.CONTENT_TYPE_HTML = 'text/html'

magpie.api.generic.CONTENT_TYPE_JSON = 'application/json'

magpie.api.generic.FORMAT_TYPE_MAPPING

magpie.api.generic.SUPPORTED_ACCEPT_TYPES

magpie.api.generic.get_authenticate_headers(request: pyramid.request.Request, error_type: magpie.typedefs.Str = 'invalid_token') → magpie.typedefs.HeadersType | None

Obtains all required headers by 401 responses based on executed request.

Parameters:

• request – request that was sent to attempt authentication or access which must respond with Unauthorized.

• error_type – Additional detail of the cause of error. Must be one of (invalid_request, invalid_token, insufficient_scope).

magpie.api.generic.get_header(header_name: magpie.typedefs.Str, header_container: magpie.typedefs.AnyHeadersType, default: magpie.typedefs.Str | None, magpie.typedefs.Str | List[magpie.typedefs.Str] | None, bool = None, split: magpie.typedefs.Str | List[magpie.typedefs.Str] | None = None, multi: bool = False, pop: bool = False) → magpie.typedefs.Str | List[magpie.typedefs.Str] | None

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=';').

Parameters:

• header_name – Header to find.

• header_container – Where to look for header_name.

• default – Value to returned if header_container is invalid or header_name could not be found.

• split – Character(s) to use to split the found header_name.

• multi – Return extracted header as array of multiple values or return a single value on fist match.

• pop – Remove the header from the container if found.

Returns:

Found header value(s) if applicable.

magpie.api.generic.get_logger(name: magpie.typedefs.Str, level: int | None = None, force_stdout: bool = None, message_format: magpie.typedefs.Str | None = None, datetime_format: magpie.typedefs.Str | None = 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.

magpie.api.generic.is_magpie_ui_path(request: pyramid.request.Request) → bool

Determines if the request path corresponds to any Magpie UI location.

magpie.api.generic.LOGGER

class magpie.api.generic.RemoveSlashNotFoundViewFactory(notfound_view=None)

Bases: object

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

__call__(request)

magpie.api.generic.internal_server_error(request: pyramid.request.Request) → pyramid.httpexceptions.HTTPException

Overrides default HTTP.

magpie.api.generic.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.

magpie.api.generic.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.

See also

• http://www.restapitutorial.com/httpstatuscodes.html

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

magpie.api.generic.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 CONTENT_TYPE_JSON.

Returns:

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

magpie.api.generic.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 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.

magpie.api.generic.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 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 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 get_request_info() is applied to the response body if not already provided by a previous operation.

magpie.api.generic.get_exception_info(response: pyramid.httpexceptions.HTTPException | pyramid.request.Request | pyramid.response.Response, content: magpie.typedefs.JSON | None = None, exception_details: bool = False) → magpie.typedefs.JSON

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

magpie.api.generic.get_request_info(request: pyramid.request.Request | pyramid.httpexceptions.HTTPException, default_message: magpie.typedefs.Str | None = None, exception_details: bool = False) → magpie.typedefs.JSON

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