Skip to content

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
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
def make_response(self, content: Any) -> Union[bytes, str]:
    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""
        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
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
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(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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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(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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
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
217
218
219
220
221
222
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)

The transformation of the data being returned.

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

PARAMETER DESCRIPTION
value

TYPE: Any

Source code in esmerald/responses/base.py
177
178
179
180
181
182
183
184
185
186
@staticmethod
def transform(value: Any) -> 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=dumps, post_transform_fn=loads)
    )