Response Object

def create_response_object(
    status_code: int,
    status_message: str,
    data: Any | None = None,
    accept_header: str = "application/json",
    supported_accept_headers: list[str] | None = None,
    http_codes: dict[int, tuple[str, str]] = http_codes_en,
    json_encoder: type[json.JSONEncoder] | None = None,
    response_format: str | None = "dict",
    **kwargs: Any,
) -> tuple[Response, int] | tuple[dict[str, Any], int]:
    """Create a HTTP response object.

    The response object can be either a dictionary or a Flask Response object,
    depending on the value of `response_format`. The response will include the
    status code, a human-readable message, and optionally additional data.
    Only supports JSON responses. For other types, use custom function with
    x-alpha-custom-response-builder in the OpenAPI specification.

    Parameters
    ----------
    status_code
        HTTP status code for the response.
    status_message
        Human-readable message describing the status.
    data
        Additional data to include in the response, by default None
    accept_header
        The value of the Accept header from the request,
        by default "application/json"
    supported_accept_headers
        A list of supported MIME types for the data_type parameter.
    http_codes
        A dictionary mapping HTTP status codes to their descriptions, by
        default http_codes_en
    json_encoder
        A custom JSON encoder class to use when encoding the response data, by
        default None. If None, the default JSONEncoder will be used.
    response_format
        The type of response to create, either "flask" or "dict", by default
        "dict"

    Returns
    -------
    tuple[dict[str, Any], int]
        A tuple containing the response object as a dictionary and the HTTP
        status code. When response_format is "dict".
    tuple[Response, int]
        A tuple containing the flask.Response object and the HTTP status code.
        When response_format is "flask".
    """
    data_type = _resolve_data_type(accept_header, supported_accept_headers)

    if response_format is None:
        response_format = "dict"

    if json_encoder is None:
        # Lazily import to avoid circular import during alpha package init.
        from alpha.encoder import JSONEncoder

        json_encoder = JSONEncoder

    obj: dict[str, Any] = {
        "detail": status_message,
        "status": status_code,
        "title": http_codes[status_code][0],
        "type": data_type or "about:blank",
    }

    if response_format == "flask":
        # Importing Flask's Response class here lazily to avoid unnecessary
        # dependencies when not using Flask.
        from flask.wrappers import Response

        filtered_data, cookies = _split_cookies_from_object(data)

        if filtered_data is not None:
            obj["data"] = filtered_data

        resp = Response(
            response=json.dumps(obj, cls=json_encoder),
            status=status_code,
            mimetype=data_type,
        )

        for cookie in cookies:
            if cookie.operation == "set":
                resp.set_cookie(  # type: ignore
                    key=cookie.key,
                    value=cookie.value,
                    max_age=cookie.max_age,
                    expires=cookie.expires,
                    path=cookie.path,
                    domain=cookie.domain,
                    secure=cookie.secure,
                    httponly=cookie.httponly,
                    samesite=cookie.samesite,
                )
            if cookie.operation == "delete":
                resp.delete_cookie(  # type: ignore
                    key=cookie.key,
                    path=cookie.path,
                    domain=cookie.domain,
                )

        return resp, status_code

    if response_format == "dict":
        if data is not None:
            obj["data"] = data
        return obj, status_code

    raise ValueError("Invalid response type. Must be 'flask' or 'dict'.")