Response class

esmerald.Response

Response(content, *, status_code=HTTP_200_OK, media_type=None, background=None, headers=None, cookies=None, encoders=None)

Bases: Response, Generic[T]

Default Response object from Esmerald where it can be as the return annotation of a handler.

Esmerakd automatically will understand what time of response is going to be used and parse all the details automatically.

Example

from pydantic import BaseModel

from esmerald import Esmerald, Gateway, Response, get
from esmerald.datastructures import Cookie


@get(path="/me")
async def home() -> Response:
    return Response(
        Item(id=1, sku="sku1238"),
        headers={"SKY-HEADER": "sku-xyz"},
        cookies=[Cookie(key="sku", value="a-value")],
    )


Esmerald(routes=[Gateway(handler=home)])

PARAMETER	DESCRIPTION
content	Any content being sent to the response. TYPE: Any
status_code	The response status code. TYPE: int DEFAULT: HTTP_200_OK
media_type	The media type used in the response. TYPE: Optional[Union[MediaType, str]] DEFAULT: None
background	Any instance of a BackgroundTask or BackgroundTasks. TYPE: Optional[Union[BackgroundTask, BackgroundTasks]] DEFAULT: None
headers	Any additional headers being passed to the response. TYPE: Optional[Dict[str, Any]] DEFAULT: None
cookies	A sequence of esmerald.datastructures.Cookie objects. Read more about the Cookies. Example from esmerald import Response from esmerald.datastructures import Cookie response_cookies=[ Cookie( key="csrf", value="CIwNZNlR4XbisJF39I8yWnWX9wX4WFoz", max_age=3000, httponly=True, ) ] Response(response_cookies=response_cookies) TYPE: Optional[ResponseCookies] DEFAULT: None
encoders	A sequence of esmerald.encoders.Encoder type of objects to be used by the response object directly. Example from esmerald import Response from esmerald.encoders import PydanticEncoder, MsgSpecEncoder response_cookies=[ encoders=[PydanticEncoder, MsgSpecEncoder] ] Response(response_cookies=response_cookies) TYPE: Union[Sequence[Encoder], None] DEFAULT: None

Source code in esmerald/responses/base.py

def __init__(
    self,
    content: Annotated[
        Any,
        Doc(
            """
            Any content being sent to the response.
            """
        ),
    ],
    *,
    status_code: Annotated[
        int,
        Doc(
            """
            The response status code.
            """
        ),
    ] = status.HTTP_200_OK,
    media_type: Annotated[
        Optional[Union[MediaType, str]],
        Doc(
            """
            The media type used in the response.
            """
        ),
    ] = None,
    background: Annotated[
        Optional[Union["BackgroundTask", "BackgroundTasks"]],
        Doc(
            """
            Any instance of a [BackgroundTask or BackgroundTasks](https://esmerald.dev/background-tasks/).
            """
        ),
    ] = None,
    headers: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Any additional headers being passed to the response.
            """
        ),
    ] = None,
    cookies: Annotated[
        Optional["ResponseCookies"],
        Doc(
            """
            A sequence of `esmerald.datastructures.Cookie` objects.

            Read more about the [Cookies](https://esmerald.dev/extras/cookie-fields/?h=responsecook#cookie-from-response-cookies).

            **Example**

            ```python
            from esmerald import Response
            from esmerald.datastructures import Cookie

            response_cookies=[
                Cookie(
                    key="csrf",
                    value="CIwNZNlR4XbisJF39I8yWnWX9wX4WFoz",
                    max_age=3000,
                    httponly=True,
                )
            ]

            Response(response_cookies=response_cookies)
            ```
            """
        ),
    ] = None,
    encoders: Annotated[
        Union[Sequence[Encoder], None],
        Doc(
            """
            A sequence of `esmerald.encoders.Encoder` type of objects to be used
            by the response object directly.

            **Example**

            ```python
            from esmerald import Response
            from esmerald.encoders import PydanticEncoder, MsgSpecEncoder

            response_cookies=[
                encoders=[PydanticEncoder, MsgSpecEncoder]
            ]

            Response(response_cookies=response_cookies)
            ```
            """
        ),
    ] = None,
) -> None:
    super().__init__(
        content=content,
        status_code=status_code,
        headers=headers or {},
        media_type=media_type,
        background=cast("BackgroundTask", background),
        encoders=encoders,
    )
    self.cookies = cookies or []

media_type class-attribute instance-attribute

media_type = None

status_code class-attribute instance-attribute

status_code = None

charset class-attribute instance-attribute

charset = 'utf-8'

background instance-attribute

background = background

encoders instance-attribute

encoders = [encoder() if isclass(encoder) else encoder for encoder in encoders or _empty]

body instance-attribute

body = make_response(content)

raw_headers instance-attribute

raw_headers = []

headers property

headers

encoded_headers property

encoded_headers

cookies instance-attribute

cookies = cookies or []

make_headers

make_headers(content_headers=None)

Initializes the headers based on RFC specifications by setting appropriate conditions and restrictions.

PARAMETER	DESCRIPTION
content_headers	TYPE: Mapping[str, str] | dict[str, str] | None DEFAULT: None

PARAMETER	DESCRIPTION
content_headers	Additional headers to include (default is None). TYPE: Union[Mapping[str, str], Dict[str, str], None] DEFAULT: None

Source code in lilya/responses.py

def make_headers(
    self, content_headers: Mapping[str, str] | dict[str, str] | None = None
) -> None:
    """
    Initializes the headers based on RFC specifications by setting appropriate conditions and restrictions.

    Args:
        content_headers (Union[Mapping[str, str], Dict[str, str], None], optional): Additional headers to include (default is None).
    """
    headers: dict[str, str] = {} if content_headers is None else content_headers  # type: ignore

    if HeaderHelper.has_entity_header_status(self.status_code):
        headers = HeaderHelper.remove_entity_headers(headers)
    if HeaderHelper.has_body_message(self.status_code):
        content_type = HeaderHelper.get_content_type(
            charset=self.charset, media_type=self.media_type
        )
        if hasattr(self, "body") and self.body is not None:
            headers.setdefault("content-length", str(len(self.body)))

        # Populates the content type if exists
        if content_type is not None:
            headers.setdefault("content-type", content_type)

    raw_headers = [
        (name.encode("utf-8"), f"{value}".encode(errors="surrogateescape"))
        for name, value in headers.items()
    ]
    self.raw_headers = raw_headers

set_cookie

set_cookie(key, value='', *, path='/', domain=None, secure=False, max_age=None, expires=None, httponly=False, samesite='lax')

Sets a cookie in the response headers.

PARAMETER	DESCRIPTION
key	TYPE: str
value	TYPE: str DEFAULT: ''
path	TYPE: str DEFAULT: '/'
domain	TYPE: str | None DEFAULT: None
secure	TYPE: bool DEFAULT: False
max_age	TYPE: int | None DEFAULT: None
expires	TYPE: datetime | str | int | None DEFAULT: None
httponly	TYPE: bool DEFAULT: False
samesite	TYPE: Literal['lax', 'strict', 'none'] DEFAULT: 'lax'

PARAMETER	DESCRIPTION
key	The name of the cookie. TYPE: str
value	The value of the cookie. TYPE: str DEFAULT: ''
path	The path for which the cookie is valid (default is '/'). TYPE: str DEFAULT: '/'
domain	The domain to which the cookie belongs. TYPE: Union[str, None] DEFAULT: None
secure	If True, the cookie should only be sent over HTTPS. TYPE: bool DEFAULT: False
max_age	The maximum age of the cookie in seconds. TYPE: Union[int, None] DEFAULT: None
expires	The expiration date of the cookie. TYPE: Union[Union[datetime, str, int], None] DEFAULT: None
httponly	If True, the cookie should only be accessible through HTTP. TYPE: bool DEFAULT: False
samesite	SameSite attribute of the cookie. TYPE: Literal['lax', 'strict', 'none'] DEFAULT: 'lax'

RAISES	DESCRIPTION
AssertionError	If samesite is not one of 'strict', 'lax', or 'none'.

Source code in lilya/responses.py

def set_cookie(
    self,
    key: str,
    value: str = "",
    *,
    path: str = "/",
    domain: str | None = None,
    secure: bool = False,
    max_age: int | None = None,
    expires: datetime | str | int | None = None,
    httponly: bool = False,
    samesite: Literal["lax", "strict", "none"] = "lax",
) -> None:
    """
    Sets a cookie in the response headers.

    Args:
        key (str): The name of the cookie.
        value (str, optional): The value of the cookie.
        path (str, optional): The path for which the cookie is valid (default is '/').
        domain (Union[str, None], optional): The domain to which the cookie belongs.
        secure (bool, optional): If True, the cookie should only be sent over HTTPS.
        max_age (Union[int, None], optional): The maximum age of the cookie in seconds.
        expires (Union[Union[datetime, str, int], None], optional): The expiration date of the cookie.
        httponly (bool, optional): If True, the cookie should only be accessible through HTTP.
        samesite (Literal["lax", "strict", "none"], optional): SameSite attribute of the cookie.

    Raises:
        AssertionError: If samesite is not one of 'strict', 'lax', or 'none'.
    """
    cookie: http.cookies.BaseCookie[str] = http.cookies.SimpleCookie()
    cookie[key] = value
    if max_age is not None:
        cookie[key]["max-age"] = max_age
    if expires is not None:
        if isinstance(expires, datetime):
            cookie[key]["expires"] = format_datetime(expires, usegmt=True)
        else:
            cookie[key]["expires"] = expires
    if path is not None:
        cookie[key]["path"] = path
    if domain is not None:
        cookie[key]["domain"] = domain
    if secure:
        cookie[key]["secure"] = True
    if httponly:
        cookie[key]["httponly"] = True
    if samesite is not None:
        assert samesite.lower() in [
            "strict",
            "lax",
            "none",
        ], "samesite must be either 'strict', 'lax' or 'none'"
        cookie[key]["samesite"] = samesite
    cookie_val = cookie.output(header="").strip()
    self.headers.add("set-cookie", cookie_val.encode("utf-8"))

delete_cookie

delete_cookie(key, path='/', domain=None, secure=False, httponly=False, samesite='lax')

Deletes a cookie in the response headers by setting its max age and expiration to 0.

PARAMETER	DESCRIPTION
key	TYPE: str
path	TYPE: str DEFAULT: '/'
domain	TYPE: str | None DEFAULT: None
secure	TYPE: bool DEFAULT: False
httponly	TYPE: bool DEFAULT: False
samesite	TYPE: Literal['lax', 'strict', 'none'] DEFAULT: 'lax'

PARAMETER	DESCRIPTION
key	The name of the cookie to delete. TYPE: str
path	The path for which the cookie is valid (default is '/'). TYPE: str DEFAULT: '/'
domain	The domain to which the cookie belongs. TYPE: Union[str, None] DEFAULT: None
secure	If True, the cookie should only be sent over HTTPS. TYPE: bool DEFAULT: False
httponly	If True, the cookie should only be accessible through HTTP. TYPE: bool DEFAULT: False
samesite	SameSite attribute of the cookie. TYPE: Literal['lax', 'strict', 'none'] DEFAULT: 'lax'

Source code in lilya/responses.py

def delete_cookie(
    self,
    key: str,
    path: str = "/",
    domain: str | None = None,
    secure: bool = False,
    httponly: bool = False,
    samesite: Literal["lax", "strict", "none"] = "lax",
) -> None:
    """
    Deletes a cookie in the response headers by setting its max age and expiration to 0.

    Args:
        key (str): The name of the cookie to delete.
        path (str, optional): The path for which the cookie is valid (default is '/').
        domain (Union[str, None], optional): The domain to which the cookie belongs.
        secure (bool, optional): If True, the cookie should only be sent over HTTPS.
        httponly (bool, optional): If True, the cookie should only be accessible through HTTP.
        samesite (Literal["lax", "strict", "none"], optional): SameSite attribute of the cookie.
    """
    self.set_cookie(
        key,
        max_age=0,
        expires=0,
        path=path,
        domain=domain,
        secure=secure,
        httponly=httponly,
        samesite=samesite,
    )

message

message(prefix)

PARAMETER	DESCRIPTION
prefix	TYPE: str

Source code in lilya/responses.py

def message(self, prefix: str) -> dict[str, Any]:
    return {
        "type": prefix + "http.response.start",
        "status": self.status_code,
        "headers": self.encoded_headers,
    }

transform staticmethod

transform(value, *, encoders=None)

The transformation of the data being returned.

Supports all the default encoders from Lilya and custom from Esmerald.

PARAMETER	DESCRIPTION
value	TYPE: Any
encoders	TYPE: Union[Sequence[Encoder], None] DEFAULT: None

Source code in esmerald/responses/base.py

@staticmethod
def transform(
    value: Any, *, encoders: Union[Sequence[Encoder], None] = None
) -> Dict[str, Any]:
    """
    The transformation of the data being returned.

    Supports all the default encoders from Lilya and custom from Esmerald.
    """
    return cast(
        Dict[str, Any],
        json_encoder(
            value,
            json_encode_fn=partial(dumps, option=OPT_SERIALIZE_NUMPY | OPT_OMIT_MICROSECONDS),
            post_transform_fn=loads,
            with_encoders=encoders,
        ),
    )

make_response

make_response(content)

PARAMETER	DESCRIPTION
content	TYPE: Any

Source code in esmerald/responses/base.py

def make_response(self, content: Any) -> Union[bytes, str]:
    # here we need lilyas encoders not only esmerald encoders
    # in case no extra encoders are defined use the default by passing None
    encoders = (
        (
            (
                *self.encoders,
                *LILYA_ENCODER_TYPES.get(),
            )
        )
        if self.encoders
        else None
    )
    try:
        if (
            content is None
            or content is NoReturn
            and (
                self.status_code < 100
                or self.status_code
                in {status.HTTP_204_NO_CONTENT, status.HTTP_304_NOT_MODIFIED}
            )
        ):
            return b""
        # switch to a special mode for MediaType.JSON
        if self.media_type == MediaType.JSON:
            return cast(
                bytes,
                json_encoder(
                    content,
                    json_encode_fn=partial(
                        dumps, option=OPT_SERIALIZE_NUMPY | OPT_OMIT_MICROSECONDS
                    ),
                    post_transform_fn=None,
                    with_encoders=encoders,
                ),
            )
        return super().make_response(content)
    except (AttributeError, ValueError, TypeError) as e:  # pragma: no cover
        raise ImproperlyConfigured("Unable to serialize response content") from e