Decorators

Response Wrapper

The @wrap_response decorator standardises all API endpoint responses into the ApiResponse contract, a TypedDict with four required fields:

{
    "code":   int,   # HTTP status code
    "status": str,   # "success" | "error" | "failure"
    "result": ...,   # payload on success, None on error/failure
    "error":  ...,   # error detail on error/failure, None on success
}

status semantics:

• "success" — 1XX / 2XX / 3XX responses

• "error" — 4XX managed errors (ServiceException, AuthorizationException)

• "failure" — 5XX server errors (InternalServerError or unhandled exceptions)

Usage example:

# -*- coding: utf-8 -*-

from core_https import HTTPStatus
from core_apis.decorators import wrap_response

@wrap_response
def get_item(item_id: int):
    return HTTPStatus.OK, {"id": item_id, "name": "Widget"}

# Returns:
# {"code": 200, "status": "success", "result": {"id": 1, "name": "Widget"}, "error": None}

Unhandled exceptions are caught and mapped to a generic 500 InternalServerError response, internal details are never disclosed to callers.

Response wrapper decorator for standardizing API responses.

This module provides a decorator that wraps API endpoint functions to ensure consistent response formatting across the application. All responses follow a standardized structure with proper status codes and error handling.

class core_apis.decorators.response_wrapper.ApiResponse

Bases: TypedDict

Standardised API response envelope returned by wrap_response.

Parameters:

• code – HTTP status code (integer).

• status – Response status string: "success", "error", or "failure".

• result – Response payload. Present on successful responses only.

• error – Error detail. Present on error/failure responses only.

code: int

status: str

result: Dict[str, Any] | None

error: ErrorInfo | None

core_apis.decorators.response_wrapper.wrap_response(fnc: Callable[[...], Tuple[HTTPStatus, Any]]) → Callable[[...], ApiResponse]

This decorator provides a generic mechanism to return the response payload for the endpoints in the same format. This way each router or controller does not need to take care of it. It returns the response into the below format…

Response payload:
    {
        "code": 2XX | 4XX | 5XX,
        "status": "success" | "error" | "failure",
        "result": ...   # on success
        "error": ...,   # on error / failure
    }

Where:
    code:
        - 2XX -> For success responses.
        - 4XX -> For service-managed errors.
        - 5XX -> For unmanaged or internal server errors.

    status:
        Contains the text: "success", "failure", or "error". Where "failure"
        is for HTTP status response values from 500 to 599, "error" is for
        statuses from 400 to 499, and "success" is for everything
        else (e.g. 1XX, 2XX and 3XX responses).

    result:
        Contains the result. Present on successful responses only.

    error:
        Contains the error detail. Present on error/failure responses only.