:mod:`magpie.api.exception` =========================== .. py:module:: magpie.api.exception Module Contents --------------- .. data:: RAISE_RECURSIVE_SAFEGUARD_MAX :annotation: = 5 .. data:: RAISE_RECURSIVE_SAFEGUARD_COUNT :annotation: = 0 .. function:: 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 :class:`HTTPInternalServerError`. Exceptions are generated using the standard output method. :param param: parameter value to evaluate :param 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 :param paramName: name of the tested parameter returned in response if specified for debugging purposes :param httpError: derived exception to raise on test failure (default: `HTTPBadRequest`) :param httpKWArgs: additional keyword arguments to pass to `httpError` if called in case of HTTP exception :param msgOnFail: message details to return in HTTP exception if flag condition failed :param content: json formatted additional content to provide in case of exception :param contentType: format in which to return the exception (one of `magpie.common.SUPPORTED_CONTENT_TYPES`) :param notNone: test that `param` is None type :param notEmpty: test that `param` is an empty string :param notIn: test that `param` does not exist in `paramCompare` values :param notEqual: test that `param` is not equal to `paramCompare` value :param isTrue: test that `param` is `True` :param isFalse: test that `param` is `False` :param isNone: test that `param` is None type :param isEmpty: test `param` for an empty string :param isIn: test that `param` exists in `paramCompare` values :param isEqual: test that `param` equals `paramCompare` value :param ofType: test that `param` is of same type as specified by `paramCompare` type :param 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`) :raises `HTTPInternalServerError`: for evaluation error :return: nothing if all tests passed .. function:: 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. :class:`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="...") :param call: function to call, *MUST* be specified as `lambda: ` :param fallback: function to call (if any) when `call` failed, *MUST* be `lambda: ` :param httpError: alternative exception to raise on `call` failure :param httpKWArgs: additional keyword arguments to pass to `httpError` if called in case of HTTP exception :param msgOnFail: message details to return in HTTP exception if `call` failed :param content: json formatted additional content to provide in case of exception :param contentType: format in which to return the exception (one of `magpie.common.SUPPORTED_CONTENT_TYPES`) :raises httpError: on `call` failure :raises `HTTPInternalServerError`: on `fallback` failure :return: whichever return value `call` might have if no exception occurred .. function:: 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) :param httpSuccess: any derived class from base `HTTPSuccessful` (default: `HTTPOk`) :param httpKWArgs: additional keyword arguments to pass to `httpSuccess` when called :param detail: additional message information (default: empty) :param content: json formatted content to include :param contentType: format in which to return the exception (one of `magpie.common.SUPPORTED_CONTENT_TYPES`) :return `HTTPSuccessful`: formatted successful with additional details and HTTP code .. function:: 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). .. seealso:: :func:`valid_http` for HTTP successful calls :param httpError: any derived class from base `HTTPError` (default: `HTTPInternalServerError`) :param httpKWArgs: additional keyword arguments to pass to `httpError` if called in case of HTTP exception :param detail: additional message information (default: empty) :param content: json formatted content to include :param contentType: format in which to return the exception (one of `magpie.common.SUPPORTED_CONTENT_TYPES`) :param 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` .. function:: 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`. :param httpClass: any derived class from base `HTTPException` to verify :param 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). :param detail: additional message information (default: empty) :param content: json formatted content to include :param contentType: format in which to return the exception (one of `magpie.common.SUPPORTED_CONTENT_TYPES`) :raise `HTTPInternalServerError`: if any parameter is of invalid expected format :returns httpCode, detail, content: parameters with corrected and validated format if applicable .. function:: 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. :raise `HTTPInternalServerError`: if parsing of the json content failed :returns: formatted json content as string with added HTTP code and details .. function:: 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. :param httpClass: `HTTPException` derived class to use for output (code, generic title/explanation, etc.) :param httpKWArgs: additional keyword arguments to pass to `httpClass` when called :param jsonContent: formatted json content providing additional details for the response cause :param outputType: one of `magpie.common.SUPPORTED_CONTENT_TYPES` (default: `magpie.common.CONTENT_TYPE_PLAIN`) :return: `httpClass` instance with requested information and output type if creation succeeds :raises: `HTTPInternalServerError` instance details about requested information and output type if creation fails