TemplateResponse class

esmerald.TemplateResponse

TemplateResponse(template_name, template_engine, status_code=200, context=None, background=None, headers=None, cookies=None, media_type=MediaType.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

charset class-attribute instance-attribute

charset = 'utf-8'

status_code instance-attribute

status_code = status_code

background instance-attribute

background = background

body instance-attribute

body = self.render(content)

headers property

headers

cookies instance-attribute

cookies = cookies or []

template instance-attribute

template = template_engine.get_template(template_name)

context instance-attribute

context = context or {}

render

render(content)

PARAMETER	DESCRIPTION
content	TYPE: Any

Source code in esmerald/responses/base.py

def render(self, content: Any) -> bytes:
    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""
        if self.media_type == MediaType.JSON:
            return dumps(
                content,
                default=self.transform,
                option=OPT_SERIALIZE_NUMPY | OPT_OMIT_MICROSECONDS,
            )
        return super().render(content)
    except (AttributeError, ValueError, TypeError) as e:  # pragma: no cover
        raise ImproperlyConfigured("Unable to serialize response content") from e

init_headers

init_headers(headers=None)

PARAMETER	DESCRIPTION
headers	TYPE: Optional[Mapping[str, str]] DEFAULT: None

Source code in .venv/lib/python3.8/site-packages/starlette/responses.py

def init_headers(
    self, headers: typing.Optional[typing.Mapping[str, str]] = None
) -> None:
    if headers is None:
        raw_headers: typing.List[typing.Tuple[bytes, bytes]] = []
        populate_content_length = True
        populate_content_type = True
    else:
        raw_headers = [
            (k.lower().encode("latin-1"), v.encode("latin-1"))
            for k, v in headers.items()
        ]
        keys = [h[0] for h in raw_headers]
        populate_content_length = b"content-length" not in keys
        populate_content_type = b"content-type" not in keys

    body = getattr(self, "body", None)
    if (
        body is not None
        and populate_content_length
        and not (self.status_code < 200 or self.status_code in (204, 304))
    ):
        content_length = str(len(body))
        raw_headers.append((b"content-length", content_length.encode("latin-1")))

    content_type = self.media_type
    if content_type is not None and populate_content_type:
        if content_type.startswith("text/"):
            content_type += "; charset=" + self.charset
        raw_headers.append((b"content-type", content_type.encode("latin-1")))

    self.raw_headers = raw_headers

set_cookie

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

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

Source code in .venv/lib/python3.8/site-packages/starlette/responses.py

def set_cookie(
    self,
    key: str,
    value: str = "",
    max_age: typing.Optional[int] = None,
    expires: typing.Optional[typing.Union[datetime, str, int]] = None,
    path: str = "/",
    domain: typing.Optional[str] = None,
    secure: bool = False,
    httponly: bool = False,
    samesite: typing.Optional[typing.Literal["lax", "strict", "none"]] = "lax",
) -> 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.raw_headers.append((b"set-cookie", cookie_val.encode("latin-1")))

delete_cookie

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

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

Source code in .venv/lib/python3.8/site-packages/starlette/responses.py

def delete_cookie(
    self,
    key: str,
    path: str = "/",
    domain: typing.Optional[str] = None,
    secure: bool = False,
    httponly: bool = False,
    samesite: typing.Optional[typing.Literal["lax", "strict", "none"]] = "lax",
) -> None:
    self.set_cookie(
        key,
        max_age=0,
        expires=0,
        path=path,
        domain=domain,
        secure=secure,
        httponly=httponly,
        samesite=samesite,
    )

transform staticmethod

transform(value)

The transformation of the data being returned.

It supports Pydantic models, dataclasses and msgspec.Struct.

PARAMETER	DESCRIPTION
value	TYPE: Any

Source code in esmerald/responses/base.py

@staticmethod
def transform(value: Any) -> Dict[str, Any]:
    """
    The transformation of the data being returned.

    It supports Pydantic models, `dataclasses` and `msgspec.Struct`.
    """
    if isinstance(value, BaseModel):
        return value.model_dump()
    if is_dataclass(value):
        return dataclasses.asdict(value)
    if isinstance(value, msgspec.Struct):
        return msgspec.structs.asdict(value)
    raise TypeError("unsupported type")  # pragma: no cover