TemplateResponse class

esmerald.TemplateResponse

TemplateResponse(template_name, template_engine, status_code=200, context=None, background=None, headers=None, cookies=None, media_type=HTML)

Bases: Response

PARAMETER	DESCRIPTION
template_name	TYPE: str
template_engine	TYPE: TemplateEngineProtocol
status_code	TYPE: int DEFAULT: 200
context	TYPE: Optional[Dict[str, Any]] DEFAULT: None
background	TYPE: Optional[Union[BackgroundTask, BackgroundTasks]] DEFAULT: None
headers	TYPE: Optional[Dict[str, Any]] DEFAULT: None
cookies	TYPE: Optional[ResponseCookies] DEFAULT: None
media_type	TYPE: Union[MediaType, str] DEFAULT: HTML

Source code in esmerald/responses/template.py

def __init__(
    self,
    template_name: str,
    template_engine: "TemplateEngineProtocol",
    status_code: int = 200,
    context: Optional[Dict[str, Any]] = None,
    background: Optional[Union["BackgroundTask", "BackgroundTasks"]] = None,
    headers: Optional[Dict[str, Any]] = None,
    cookies: Optional["ResponseCookies"] = None,
    media_type: Union[MediaType, str] = MediaType.HTML,
):
    if media_type == MediaType.JSON:  # we assume this is the default
        suffixes = PurePath(template_name).suffixes
        for suffix in suffixes:
            _type = guess_type("name" + suffix)[0]
            if _type:
                media_type = _type
                break
        else:
            media_type = MediaType.TEXT  # pragma: no cover

    self.template = template_engine.get_template(template_name)
    self.context = context or {}
    content = self.template.render(**context)
    super().__init__(
        content=content,
        status_code=status_code,
        headers=headers,
        media_type=media_type,
        background=background,
        cookies=cookies,
    )

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

cookies instance-attribute

cookies = cookies or []

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

template instance-attribute

template = get_template(template_name)

context instance-attribute

context = context or {}

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

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,
        ),
    )