1
2
3
4
5
6
7
8
9
10
11
12
13
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
93
94
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
|
API
===
Describes the module API with detailed explanations of functions parameters.
.. module:: aiohttp_jinja2
.. highlight:: python
APP_KEY
-------
.. data:: APP_KEY
The key name in :class:`aiohttp.web.Application` dictionary,
``'aiohttp_jinja2_environment'`` for storing :term:`jinja2`
environment object (:class:`jinja2.Environment`).
Usually you don't need to operate with *application* manually, left
it to :mod:`aiohttp_jinja2` functions.
setup
-----
.. function:: setup(app, *args, app_key=APP_KEY, context_processors=(), \
autoescape=True, \
filters=None, default_helpers=True, **kwargs)
Function responsible for initializing templating system on application. It
must be called before freezing or running the application in order to use
*aiohttp-jinja*.
:param app: :class:`aiohttp.web.Application` instance to initialize template
system on.
:param str app_key: optional key that will be used to access templating
environment from application dictionary object. Defaults
to `aiohttp_jinja2_environment`.
:param context_processors: list of :ref:`aiohttp-web-middlewares`. These are
context processors used to rewrite or inject some
variables during the processing of a request.
:type context_processors: :class:`list`
:param autoescape: the argument is passed to :class:`jinja2.Environemnt`, see
`Autoescaping` for more details.
:param filters: extra jinja filters (`link to docs
<http://jinja.pocoo.org/docs/2.10/templates/#filters>`).
:type filters: :class:`list`
:param bool default_helpers: whether to use default global helper in
templates provided by package
:mod:`aiohttp_jinja2.helpers` or not.
:param ``*args``: positional arguments passed into environment constructor.
:param ``**kwargs``: any arbitrary keyword arguments you want to pass to
:class:`jinja2.Environment` environment.
Simple initialization::
import jinja2
import aiohttp_jinja2
from aiohttp import web
app = web.Application()
aiohttp_jinja2.setup(
app,
loader=jinja2.FileSystemLoader('/path/to/templates/folder'),
)
@template
--------
.. decorator:: template(template_name, *, app_key=APP_KEY, \
encoding='utf-8', status=200)
Behaves as a decorator around view functions accepting template name that
should be used to render the response. Supports both synchronous and
asynchronous functions.
:param str template_name: name of the template file that will be looked up
by the loader. Raises a 500 error in case template
was not found.
:param str app_key: optional key that will be used to access templating
environment from application dictionary object. Defaults
to `aiohttp_jinja2_environment`.
:param str encoding: encoding that will be set as a charset property on the
response for rendered template, default to utf-8.
:params int status: http status code that will be set on resulting response.
Simple usage example::
@jinja2.template('tmpl.jinja2')
async def handler(request):
context = {'foo': 'bar'}
return context
app.router.add_get('/tmpl', handler)
render_string
-------------
.. function:: render_string(template_name, request, context, *, \
app_key=APP_KEY)
Renders template specified and returns resulting string.
:param str template_name: Name of the template you want to render. Usually
it's a filename without extension on your
filesystem.
:param request: aiohttp request associated with an application where
aiohttp-jinja rendering is configured.
:type request: :class:`aiohttp.web.Request`
:param dict context: dictionary used as context when rendering the template.
:param str app_key: optional key that will be used to access templating
environment from application dictionary object. Defaults
to `aiohttp_jinja2_environment`.
render_string_async
-------------------
.. function:: render_string_async(template_name, request, context, *, \
app_key=APP_KEY)
:async:
Async version of ``render_string()``.
Replaces ``render_string()`` when ``enable_async=True`` is passed to the
``setup()`` call.
See ``render_string()`` for parameter usage.
render_template
---------------
.. function:: render_template(template_name, request, context, *, \
app_key=APP_KEY, encoding='utf-8', status=200)
:param str template_name: Name of the template you want to render.
:param request: aiohttp request associated with an application where
aiohttp-jinja rendering is configured.
:type request: :class:`aiohttp.web.Request`
:param dict context: dictionary used as context when rendering the template.
:param str app_key: optional key that will be used to access templating
environment from application dictionary object. Defaults
to `aiohttp_jinja2_environment`.
:param int status: http status code that will be set on resulting response.
Assuming the initialization from the example above has been done::
async def handler(request):
context = {'foo': 'bar'}
response = aiohttp_jinja2.render_template('tmpl.jinja2',
request,
context)
return response
app.router.add_get('/tmpl', handler)
render_template_async
---------------------
.. function:: render_template_async( \
template_name, request, context, *, \
app_key=APP_KEY, encoding='utf-8', status=200)
:async:
Async version of ``render_template()``.
Replaces ``render_template()`` when ``enable_async=True`` is passed to the
``setup()`` call.
See ``render_template()`` for parameter usage.
.. function:: get_env(app, *, app_key=APP_KEY)
Get aiohttp-jinja2 environment from an application instance by key.
:param app: :class:`aiohttp.web.Application` instance to get variables from.
:param str app_key: optional key that will be used to access templating
environment from application dictionary object. Defaults
to `aiohttp_jinja2_environment`.
|
