magpie.api.exception

Module Contents

magpie.api.exception.RAISE_RECURSIVE_SAFEGUARD_MAX = 5

magpie.api.exception.RAISE_RECURSIVE_SAFEGUARD_COUNT = 0

magpie.api.exception.verify_param(param, paramCompare=None, paramName=None, withParam=True, httpError=HTTPBadRequest, httpKWArgs=None, msgOnFail='', content=None, contentType=CONTENT_TYPE_JSON, notNone=False, notEmpty=False, notIn=False, notEqual=False, isTrue=False, isFalse=False, isNone=False, isEmpty=False, isIn=False, isEqual=False, ofType=False) → None

Evaluate various parameter combinations given the requested verification flags. Given a failing verification, directly raises the specified httpError. Invalid usage exceptions generated by this verification process are treated as HTTPInternalServerError. Exceptions are generated using the standard output method.

Parameters:

• param – parameter value to evaluate
• paramCompare – other value(s) to test param against, can be an iterable (single value resolved as iterable unless None) to test for None type, use isNone/notNone flags instead
• paramName – name of the tested parameter returned in response if specified for debugging purposes
• httpError – derived exception to raise on test failure (default: HTTPBadRequest)
• httpKWArgs – additional keyword arguments to pass to httpError if called in case of HTTP exception
• msgOnFail – message details to return in HTTP exception if flag condition failed
• content – json formatted additional content to provide in case of exception
• contentType – format in which to return the exception (one of magpie.common.SUPPORTED_CONTENT_TYPES)
• notNone – test that param is None type
• notEmpty – test that param is an empty string
• notIn – test that param does not exist in paramCompare values
• notEqual – test that param is not equal to paramCompare value
• isTrue – test that param is True
• isFalse – test that param is False
• isNone – test that param is None type
• isEmpty – test param for an empty string
• isIn – test that param exists in paramCompare values
• isEqual – test that param equals paramCompare value
• ofType – test that param is of same type as specified by paramCompare type
• withParam – on raise, adds values of param, paramName and paramCompare to json response if specified

Raises:

• HTTPError – if tests fail, specified exception is raised (default: HTTPBadRequest)
• HTTPInternalServerError – for evaluation error

Returns:

nothing if all tests passed

magpie.api.exception.evaluate_call(call, fallback=None, httpError=HTTPInternalServerError, httpKWArgs=None, msgOnFail='', content=None, contentType=CONTENT_TYPE_JSON) → Any

Evaluates the specified call with a wrapped HTTP exception handling. On failure, tries to call fallback if specified, and finally raises the specified httpError. Any potential error generated by fallback or httpError themselves are treated as.

HTTPInternalServerError. Exceptions are generated using the standard output method formatted based on the specified contentType.

Example:

normal call:

try:
    res = func(args)
except Exception as e:
    fb_func()
    raise HTTPExcept(e.message)

wrapped call:

res = evaluate_call(lambda: func(args), fallback=lambda: fb_func(), httpError=HTTPExcept, msgOnFail="...")

Parameters:

• call – function to call, MUST be specified as lambda: <function_call>
• fallback – function to call (if any) when call failed, MUST be lambda: <function_call>
• httpError – alternative exception to raise on call failure
• httpKWArgs – additional keyword arguments to pass to httpError if called in case of HTTP exception
• msgOnFail – message details to return in HTTP exception if call failed
• content – json formatted additional content to provide in case of exception
• contentType – format in which to return the exception (one of magpie.common.SUPPORTED_CONTENT_TYPES)

Raises:

• httpError – on call failure
• HTTPInternalServerError – on fallback failure

Returns:

whichever return value call might have if no exception occurred

magpie.api.exception.valid_http(httpSuccess=HTTPOk, httpKWArgs=None, detail='', content=None, contentType=CONTENT_TYPE_JSON) → HTTPException

Returns successful HTTP with standardized information formatted with content type. (see :function:`raise_http` for HTTP error calls)

Parameters:

• httpSuccess – any derived class from base HTTPSuccessful (default: HTTPOk)
• httpKWArgs – additional keyword arguments to pass to httpSuccess when called
• detail – additional message information (default: empty)
• content – json formatted content to include
• contentType – format in which to return the exception (one of magpie.common.SUPPORTED_CONTENT_TYPES)

Return HTTPSuccessfulHTTPSuccessful:  

formatted successful with additional details and HTTP code

magpie.api.exception.raise_http(httpError=HTTPInternalServerError, httpKWArgs=None, detail='', content=None, contentType=CONTENT_TYPE_JSON, nothrow=False) → Optional[HTTPException]

Raises error HTTP with standardized information formatted with content type.

The content contains the corresponding http error code, the provided message as detail and optional specified additional json content (kwarg dict).

See also

valid_http() for HTTP successful calls

Parameters:

• httpError – any derived class from base HTTPError (default: HTTPInternalServerError)
• httpKWArgs – additional keyword arguments to pass to httpError if called in case of HTTP exception
• detail – additional message information (default: empty)
• content – json formatted content to include
• contentType – format in which to return the exception (one of magpie.common.SUPPORTED_CONTENT_TYPES)
• nothrow – returns the error response instead of raising it automatically, but still handles execution errors

Raises:

HTTPError – formatted raised exception with additional details and HTTP code

Returns:

HTTPError formatted exception with additional details and HTTP code only if nothrow is True

magpie.api.exception.validate_params(httpClass, httpBase, detail, content, contentType) → Tuple[int, Str, JSON]

Validates parameter types and formats required by :function:`valid_http` and :function:`raise_http`.

Parameters:

• httpClass – any derived class from base HTTPException to verify
• httpBase – any derived sub-class(es) from base HTTPException as minimum requirement for httpClass (ie: 2xx, 4xx, 5xx codes). Can be a single class of an iterable of possible requirements (any).
• detail – additional message information (default: empty)
• content – json formatted content to include
• contentType – format in which to return the exception (one of magpie.common.SUPPORTED_CONTENT_TYPES)

Raises:

HTTPInternalServerError – if any parameter is of invalid expected format

Returns httpCode, detail, content:  

parameters with corrected and validated format if applicable

magpie.api.exception.format_content_json_str(httpCode, detail, content, contentType)

Inserts the code, details, content and type within the body using json format. Includes also any other specified json formatted content in the body. Returns the whole json body as a single string for output.

Raises:HTTPInternalServerError – if parsing of the json content failed Returns:formatted json content as string with added HTTP code and details

magpie.api.exception.generate_response_http_format(httpClass, httpKWArgs, jsonContent, outputType=CONTENT_TYPE_PLAIN) → PyramidResponse

Formats the HTTP response output according to desired outputType using provided HTTP code and content.

Parameters:

• httpClass – HTTPException derived class to use for output (code, generic title/explanation, etc.)
• httpKWArgs – additional keyword arguments to pass to httpClass when called
• jsonContent – formatted json content providing additional details for the response cause
• outputType – one of magpie.common.SUPPORTED_CONTENT_TYPES (default: magpie.common.CONTENT_TYPE_PLAIN)

Returns:

httpClass instance with requested information and output type if creation succeeds

Raises:

HTTPInternalServerError instance details about requested information and output type if creation fails