Skip to content

Jinja

Jinja2 (renderer) decorator factory.

Source code in fasthx/jinja.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
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
174
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
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
@dataclass(frozen=True, slots=True)
class Jinja:
    """Jinja2 (renderer) decorator factory."""

    templates: Jinja2Templates
    """The Jinja2 templates of the application."""

    make_context: JinjaContextFactory = JinjaContext.unpack_result
    """
    Function that will be used by default to convert a route's return value into
    a Jinja rendering context. The default value is `JinjaContext.unpack_result`.
    """

    @deprecated("Deprecated and will be removed in the future. Please use `hx()` instead.")
    def __call__(
        self,
        template_name: str,
        *,
        no_data: bool = False,
        make_context: JinjaContextFactory | None = None,
    ) -> Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]:
        """
        Deprecated and will be removed in the future. Please use `hx()` instead.

        Alias for `hx()`.
        """
        warnings.warn(
            (
                "Jinja.__call__() is deprecated and will be removed in the future. "
                "Please use hx() instead."
            ),
            DeprecationWarning,
            stacklevel=1,
        )
        return self.hx(template_name, no_data=no_data, make_context=make_context)

    def hx(
        self,
        template_name: str,
        *,
        no_data: bool = False,
        make_context: JinjaContextFactory | None = None,
    ) -> Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]:
        """
        Decorator for rendering a route's return value to HTML using the Jinja2 template
        with the given name, if the request was an HTMX one.

        Arguments:
            template_name: The name of the Jinja2 template to use.
            no_data: If set, the route will only accept HTMX requests.
            make_context: Route-specific override for the `make_context` property.

        Returns:
            The rendered HTML for HTMX requests, otherwise the route's unchanged return value.
        """
        if make_context is None:
            # No route-specific override.
            make_context = self.make_context

        def render(result: Any, *, context: dict[str, Any], request: Request) -> str | Response:
            return self._make_response(
                template_name,
                jinja_context=make_context(route_result=result, route_context=context),
                request=request,
            )

        return hx(render, no_data=no_data)

    def page(
        self, template_name: str, *, make_context: JinjaContextFactory | None = None
    ) -> Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]:
        """
        Decorator for rendering a route's return value to HTML using the Jinja2 template
        with the given name. This decorator triggers HTML rendering regardless of whether
        the request was HTMX or not.

        Arguments:
            template_name: The name of the Jinja2 template to use.
            make_context: Route-specific override for the `make_context` property.
        """
        if make_context is None:
            # No route-specific override.
            make_context = self.make_context

        def render(result: Any, *, context: dict[str, Any], request: Request) -> str | Response:
            return self._make_response(
                template_name,
                jinja_context=make_context(route_result=result, route_context=context),
                request=request,
            )

        return page(render)

    @deprecated("Deprecated and will be removed in the future. Please use `hx()` instead.")
    def template(
        self,
        template_name: str,
        *,
        no_data: bool = False,
        make_context: JinjaContextFactory | None = None,
    ) -> Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]:
        """
        Deprecated and will be removed in the future. Please use `hx()` instead.

        Alias for `hx()`.
        """
        warnings.warn(
            (
                "Jinja.template() is deprecated and will be removed in the future. "
                "Please use hx() instead."
            ),
            DeprecationWarning,
            stacklevel=1,
        )
        return self.hx(template_name, no_data=no_data, make_context=make_context)

    def _make_response(
        self,
        template_name: str,
        *,
        jinja_context: dict[str, Any],
        request: Request,
    ) -> str | Response:
        """
        Creates the HTML response using the given Jinja template name and context.
        """
        # The reason for returning string from this method is to let `hx()` or `page()` create
        # the HTML response - that way they can copy response headers and do other convenience
        # conversions.
        # The drawback is that users lose some of the baked-in debug utilities of TemplateResponse.
        # This can be worked around by using a rendering context factory that includes the route's
        # dependencies in the Jinja context. Then this method can be overridden to take the Response
        # object from the context and copy the header from it into TemplateResponse.
        result = self.templates.TemplateResponse(
            name=template_name,
            context=jinja_context,
            request=request,
        )
        return result.body.decode(result.charset)

make_context: JinjaContextFactory = JinjaContext.unpack_result class-attribute instance-attribute

Function that will be used by default to convert a route's return value into a Jinja rendering context. The default value is JinjaContext.unpack_result.

templates: Jinja2Templates instance-attribute

The Jinja2 templates of the application.

__call__(template_name, *, no_data=False, make_context=None)

Deprecated and will be removed in the future. Please use hx() instead.

Alias for hx().

Source code in fasthx/jinja.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@deprecated("Deprecated and will be removed in the future. Please use `hx()` instead.")
def __call__(
    self,
    template_name: str,
    *,
    no_data: bool = False,
    make_context: JinjaContextFactory | None = None,
) -> Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]:
    """
    Deprecated and will be removed in the future. Please use `hx()` instead.

    Alias for `hx()`.
    """
    warnings.warn(
        (
            "Jinja.__call__() is deprecated and will be removed in the future. "
            "Please use hx() instead."
        ),
        DeprecationWarning,
        stacklevel=1,
    )
    return self.hx(template_name, no_data=no_data, make_context=make_context)

hx(template_name, *, no_data=False, make_context=None)

Decorator for rendering a route's return value to HTML using the Jinja2 template with the given name, if the request was an HTMX one.

Parameters:

Name Type Description Default
template_name str

The name of the Jinja2 template to use.

 required
no_data bool

If set, the route will only accept HTMX requests.

 False
make_context JinjaContextFactory | None

Route-specific override for the make_context property.

 None

Returns:

Type Description
Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]

The rendered HTML for HTMX requests, otherwise the route's unchanged return value.
Source code in fasthx/jinja.py 
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
def hx(
    self,
    template_name: str,
    *,
    no_data: bool = False,
    make_context: JinjaContextFactory | None = None,
) -> Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]:
    """
    Decorator for rendering a route's return value to HTML using the Jinja2 template
    with the given name, if the request was an HTMX one.

    Arguments:
        template_name: The name of the Jinja2 template to use.
        no_data: If set, the route will only accept HTMX requests.
        make_context: Route-specific override for the `make_context` property.

    Returns:
        The rendered HTML for HTMX requests, otherwise the route's unchanged return value.
    """
    if make_context is None:
        # No route-specific override.
        make_context = self.make_context

    def render(result: Any, *, context: dict[str, Any], request: Request) -> str | Response:
        return self._make_response(
            template_name,
            jinja_context=make_context(route_result=result, route_context=context),
            request=request,
        )

    return hx(render, no_data=no_data)

page(template_name, *, make_context=None)

Decorator for rendering a route's return value to HTML using the Jinja2 template with the given name. This decorator triggers HTML rendering regardless of whether the request was HTMX or not.

Parameters:

Name Type Description Default
template_name str

The name of the Jinja2 template to use.

 required
make_context JinjaContextFactory | None

Route-specific override for the make_context property.

 None
Source code in fasthx/jinja.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
def page(
    self, template_name: str, *, make_context: JinjaContextFactory | None = None
) -> Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]:
    """
    Decorator for rendering a route's return value to HTML using the Jinja2 template
    with the given name. This decorator triggers HTML rendering regardless of whether
    the request was HTMX or not.

    Arguments:
        template_name: The name of the Jinja2 template to use.
        make_context: Route-specific override for the `make_context` property.
    """
    if make_context is None:
        # No route-specific override.
        make_context = self.make_context

    def render(result: Any, *, context: dict[str, Any], request: Request) -> str | Response:
        return self._make_response(
            template_name,
            jinja_context=make_context(route_result=result, route_context=context),
            request=request,
        )

    return page(render)

template(template_name, *, no_data=False, make_context=None)

Deprecated and will be removed in the future. Please use hx() instead.

Alias for hx().

Source code in fasthx/jinja.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
@deprecated("Deprecated and will be removed in the future. Please use `hx()` instead.")
def template(
    self,
    template_name: str,
    *,
    no_data: bool = False,
    make_context: JinjaContextFactory | None = None,
) -> Callable[[MaybeAsyncFunc[P, Any]], Callable[P, Coroutine[None, None, Any | Response]]]:
    """
    Deprecated and will be removed in the future. Please use `hx()` instead.

    Alias for `hx()`.
    """
    warnings.warn(
        (
            "Jinja.template() is deprecated and will be removed in the future. "
            "Please use hx() instead."
        ),
        DeprecationWarning,
        stacklevel=1,
    )
    return self.hx(template_name, no_data=no_data, make_context=make_context)

JinjaContext

Core JinjaContextFactory implementations.

Source code in fasthx/jinja.py 
14
15
16
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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class JinjaContext:
    """
    Core `JinjaContextFactory` implementations.
    """

    @classmethod
    def unpack_result(cls, *, route_result: Any, route_context: dict[str, Any]) -> dict[str, Any]:
        """
        Jinja context factory that tries to reasonably convert non-`dict` route results
        to valid Jinja contexts (the `route_context` argument is ignored).

        Supports `dict` and `Collection` instances, plus anything with `__dict__` or `__slots__`
        attributes, for example Pydantic models, dataclasses, or "standard" class instances.

        Conversion rules:

        - `dict`: returned as is.
        - `Collection`: returned as `{"items": route_context}`, available in templates as `items`.
        - Objects with `__dict__` or `__slots__`: known keys are taken from `__dict__` or `__slots__`
          and the context will be created as `{key: getattr(route_result, key) for key in keys}`,
          omitting property names starting with an underscore.
        - `None` is converted into an empty context.

        Raises:
            ValueError: If `route_result` can not be handled by any of the conversion rules.
        """
        if isinstance(route_result, dict):
            return route_result

        # Covers lists, tuples, sets, etc..
        if isinstance(route_result, Collection):
            return {"items": route_result}

        object_keys: Iterable[str] | None = None

        # __dict__ should take priority if an object has both this and __slots__.
        if hasattr(route_result, "__dict__"):
            # Covers Pydantic models and standard classes.
            object_keys = route_result.__dict__.keys()
        elif hasattr(route_result, "__slots__"):
            # Covers classes with with __slots__.
            object_keys = route_result.__slots__

        if object_keys is not None:
            return {key: getattr(route_result, key) for key in object_keys if not key.startswith("_")}

        if route_result is None:
            # Convert no response to empty context.
            return {}

        raise ValueError("Result conversion failed, unknown result type.")

    @classmethod
    def unpack_result_with_route_context(
        cls,
        *,
        route_result: Any,
        route_context: dict[str, Any],
    ) -> dict[str, Any]:
        """
        Jinja context factory that tries to reasonably convert non-`dict` route results
        to valid Jinja contexts, also including every key-value pair from `route_context`.

        Supports everything that `JinjaContext.unpack_result()` does and follows the same
        conversion rules.

        Raises:
            ValueError: If `JinjaContext.unpack_result()` raises an error or if there's
                a key conflict between `route_result` and `route_context`.
        """
        result = cls.unpack_result(route_result=route_result, route_context=route_context)
        if len(set(result.keys()) & set(route_context.keys())) > 0:
            raise ValueError("Overlapping keys in route result and route context.")

        # route_context is the keyword args of the route collected into a dict. Update and
        # return this dict rather than result, as the result might be the same object that
        # was returned by the route and someone may have a reference to it.
        route_context.update(result)
        return route_context

unpack_result(*, route_result, route_context) classmethod

Jinja context factory that tries to reasonably convert non-dict route results to valid Jinja contexts (the route_context argument is ignored).

Supports dict and Collection instances, plus anything with __dict__ or __slots__ attributes, for example Pydantic models, dataclasses, or "standard" class instances.

Conversion rules:

  • dict: returned as is.
  • Collection: returned as {"items": route_context}, available in templates as items.
  • Objects with __dict__ or __slots__: known keys are taken from __dict__ or __slots__ and the context will be created as {key: getattr(route_result, key) for key in keys}, omitting property names starting with an underscore.
  • None is converted into an empty context.

Raises:

Type Description
ValueError

If route_result can not be handled by any of the conversion rules.
Source code in fasthx/jinja.py 
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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@classmethod
def unpack_result(cls, *, route_result: Any, route_context: dict[str, Any]) -> dict[str, Any]:
    """
    Jinja context factory that tries to reasonably convert non-`dict` route results
    to valid Jinja contexts (the `route_context` argument is ignored).

    Supports `dict` and `Collection` instances, plus anything with `__dict__` or `__slots__`
    attributes, for example Pydantic models, dataclasses, or "standard" class instances.

    Conversion rules:

    - `dict`: returned as is.
    - `Collection`: returned as `{"items": route_context}`, available in templates as `items`.
    - Objects with `__dict__` or `__slots__`: known keys are taken from `__dict__` or `__slots__`
      and the context will be created as `{key: getattr(route_result, key) for key in keys}`,
      omitting property names starting with an underscore.
    - `None` is converted into an empty context.

    Raises:
        ValueError: If `route_result` can not be handled by any of the conversion rules.
    """
    if isinstance(route_result, dict):
        return route_result

    # Covers lists, tuples, sets, etc..
    if isinstance(route_result, Collection):
        return {"items": route_result}

    object_keys: Iterable[str] | None = None

    # __dict__ should take priority if an object has both this and __slots__.
    if hasattr(route_result, "__dict__"):
        # Covers Pydantic models and standard classes.
        object_keys = route_result.__dict__.keys()
    elif hasattr(route_result, "__slots__"):
        # Covers classes with with __slots__.
        object_keys = route_result.__slots__

    if object_keys is not None:
        return {key: getattr(route_result, key) for key in object_keys if not key.startswith("_")}

    if route_result is None:
        # Convert no response to empty context.
        return {}

    raise ValueError("Result conversion failed, unknown result type.")

unpack_result_with_route_context(*, route_result, route_context) classmethod

Jinja context factory that tries to reasonably convert non-dict route results to valid Jinja contexts, also including every key-value pair from route_context.

Supports everything that JinjaContext.unpack_result() does and follows the same conversion rules.

Raises:

Type Description
ValueError

If JinjaContext.unpack_result() raises an error or if there's a key conflict between route_result and route_context.
Source code in fasthx/jinja.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@classmethod
def unpack_result_with_route_context(
    cls,
    *,
    route_result: Any,
    route_context: dict[str, Any],
) -> dict[str, Any]:
    """
    Jinja context factory that tries to reasonably convert non-`dict` route results
    to valid Jinja contexts, also including every key-value pair from `route_context`.

    Supports everything that `JinjaContext.unpack_result()` does and follows the same
    conversion rules.

    Raises:
        ValueError: If `JinjaContext.unpack_result()` raises an error or if there's
            a key conflict between `route_result` and `route_context`.
    """
    result = cls.unpack_result(route_result=route_result, route_context=route_context)
    if len(set(result.keys()) & set(route_context.keys())) > 0:
        raise ValueError("Overlapping keys in route result and route context.")

    # route_context is the keyword args of the route collected into a dict. Update and
    # return this dict rather than result, as the result might be the same object that
    # was returned by the route and someone may have a reference to it.
    route_context.update(result)
    return route_context

JinjaContextFactory

Bases: Protocol

Protocol definition for methods that convert a FastAPI route's result and route context (i.e. the route's arguments) into a Jinja context (dict).

Source code in fasthx/typing.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class JinjaContextFactory(Protocol):
    """
    Protocol definition for methods that convert a FastAPI route's result and route context
    (i.e. the route's arguments) into a Jinja context (`dict`).
    """

    def __call__(self, *, route_result: Any, route_context: dict[str, Any]) -> dict[str, Any]:
        """
        Arguments:
            route_result: The result of the route.
            route_context: Every keyword argument the route received.

        Returns:
            The Jinja context dictionary.

        Raises:
            ValueError: If converting the arguments to a Jinja context fails.
        """
        ...

__call__(*, route_result, route_context)

Parameters:

Name Type Description Default
route_result Any

The result of the route.

 required
route_context dict[str, Any]

Every keyword argument the route received.

 required

Returns:

Type Description
dict[str, Any]

The Jinja context dictionary.

Raises:

Type Description
ValueError

If converting the arguments to a Jinja context fails.
Source code in fasthx/typing.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
def __call__(self, *, route_result: Any, route_context: dict[str, Any]) -> dict[str, Any]:
    """
    Arguments:
        route_result: The result of the route.
        route_context: Every keyword argument the route received.

    Returns:
        The Jinja context dictionary.

    Raises:
        ValueError: If converting the arguments to a Jinja context fails.
    """
    ...