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
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
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Context and Environment — Jinja Documentation</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" href="style.css" type="text/css">
<style type="text/css">
.syntax { background: #ffffff; }
.syntax .c { color: #888888 } /* Comment */
.syntax .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.syntax .k { color: #008800; font-weight: bold } /* Keyword */
.syntax .cm { color: #888888 } /* Comment.Multiline */
.syntax .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.syntax .c1 { color: #888888 } /* Comment.Single */
.syntax .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.syntax .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.syntax .ge { font-style: italic } /* Generic.Emph */
.syntax .gr { color: #aa0000 } /* Generic.Error */
.syntax .gh { color: #303030 } /* Generic.Heading */
.syntax .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.syntax .go { color: #888888 } /* Generic.Output */
.syntax .gp { color: #555555 } /* Generic.Prompt */
.syntax .gs { font-weight: bold } /* Generic.Strong */
.syntax .gu { color: #606060 } /* Generic.Subheading */
.syntax .gt { color: #aa0000 } /* Generic.Traceback */
.syntax .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.syntax .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.syntax .kp { color: #008800 } /* Keyword.Pseudo */
.syntax .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.syntax .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.syntax .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.syntax .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.syntax .na { color: #336699 } /* Name.Attribute */
.syntax .nb { color: #003388 } /* Name.Builtin */
.syntax .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.syntax .no { color: #003366; font-weight: bold } /* Name.Constant */
.syntax .nd { color: #555555 } /* Name.Decorator */
.syntax .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.syntax .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.syntax .nl { color: #336699; font-style: italic } /* Name.Label */
.syntax .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.syntax .py { color: #336699; font-weight: bold } /* Name.Property */
.syntax .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.syntax .nv { color: #336699 } /* Name.Variable */
.syntax .ow { color: #008800 } /* Operator.Word */
.syntax .w { color: #bbbbbb } /* Text.Whitespace */
.syntax .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.syntax .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.syntax .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.syntax .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.syntax .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.syntax .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.syntax .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.syntax .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.syntax .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.syntax .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.syntax .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.syntax .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.syntax .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.syntax .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.syntax .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.syntax .bp { color: #003388 } /* Name.Builtin.Pseudo */
.syntax .vc { color: #336699 } /* Name.Variable.Class */
.syntax .vg { color: #dd7700 } /* Name.Variable.Global */
.syntax .vi { color: #3333bb } /* Name.Variable.Instance */
.syntax .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
</style>
</head>
<body>
<div id="content">
<h1 class="heading"><span>Jinja</span></h1>
<h2 class="subheading">Context and Environment</h2>
<div id="toc">
<h2>Navigation</h2>
<ul>
<li><a href="index.html">back to index</a></li>
</ul>
<h2>Contents</h2>
<ul class="contents">
<li><a href="#environment">Environment</a></li>
<li><a href="#context">Context</a></li>
<li><a href="#exceptions">Exceptions</a></li>
</ul>
</div>
<div id="contentwrapper">
<p>The two central objects in Jinja are the <cite>Environment</cite> and <cite>Context</cite>. Both
are designed to be subclassed by applications if they need to extend Jinja.</p>
<div class="section">
<h2><a id="environment" name="environment">Environment</a></h2>
<p>The initialization parameters are already covered in the <a class="reference" href="./devintro.html">Quickstart</a> thus
not repeated here.</p>
<p>But beside those configurable instance variables there are some functions used
in the template evaluation code you may want to override:</p>
<p><strong>def</strong> <cite>parse</cite> <em>(source, filename)</em>:</p>
<blockquote>
Parse the sourcecode and return the abstract syntax tree. This tree of
nodes is used by the <a class="reference" href="./translators.html">translators</a> to convert the template into
executable source- or bytecode.</blockquote>
<p><strong>def</strong> <cite>lex</cite> <em>(source, filename)</em>:</p>
<blockquote>
<p>Tokenize the given sourcecode and return a generator of tuples in the
form <tt class="docutils literal"><span class="pre">(lineno,</span> <span class="pre">token,</span> <span class="pre">value)</span></tt>. The filename is just used in the
exceptions raised.</p>
<p><strong>New in Jinja 1.1</strong></p>
</blockquote>
<p><strong>def</strong> <cite>from_string</cite> <em>(source)</em>:</p>
<blockquote>
Load and parse a template source and translate it into eval-able Python
code. This code is wrapped within a <cite>Template</cite> class that allows you to
render it.</blockquote>
<p><strong>def</strong> <cite>get_template</cite> <em>(name)</em>:</p>
<blockquote>
Load a template from a loader. If the template does not exist, you will
get a <cite>jinja.exceptions.TemplateNotFound</cite> exception.</blockquote>
<p><strong>def</strong> <cite>to_unicode</cite> <em>(self, value)</em>:</p>
<blockquote>
<p>Called to convert variables to unicode. Per default this checks if the
value is already unicode. If not it's converted to unicode using the
charset defined on the environment.</p>
<p>Also <cite>None</cite> is converted into an empty string per default.</p>
</blockquote>
<p><strong>def</strong> <cite>get_translator</cite> <em>(self, context)</em>:</p>
<blockquote>
<p>Return the translator used for i18n. A translator is an object that
provides the two functions <tt class="docutils literal"><span class="pre">gettext(string)</span></tt> and
<tt class="docutils literal"><span class="pre">ngettext(singular,</span> <span class="pre">plural,</span> <span class="pre">n)</span></tt>. Both of those functions have to
behave like the <cite>ugettext</cite> and <cite>nugettext</cite> functions described in the
python <a class="reference" href="http://docs.python.org/lib/module-gettext.html">gettext documentation</a>.</p>
<p>If you don't provide a translator a default one is used to switch
between singular and plural forms.</p>
<p>Have a look at the <a class="reference" href="./i18n.html">i18n</a> section for more information.</p>
</blockquote>
<p><strong>def</strong> <cite>get_translations</cite> <em>(self, name)</em>:</p>
<blockquote>
Get the translations for the template <cite>name</cite>. Only works if a loader
is present. See the <a class="reference" href="./i18n.html">i18n</a> section for more details.</blockquote>
<p><strong>def</strong> <cite>get_translations_for_string</cite> <em>(self, string)</em>:</p>
<blockquote>
Get the translations for the string <cite>string</cite>. This works also if no
loader is present and can be used to lookup translation strings from
templates that are loaded from dynamic resources like databases.</blockquote>
<p><strong>def</strong> <cite>apply_filters</cite> <em>(self, value, context, filters)</em>:</p>
<blockquote>
<p>Now this function is a bit tricky and you usually don't have to override
it. It's used to apply filters on a value. The Jinja expression
<tt class="docutils literal"><span class="pre">{{</span> <span class="pre">foo|escape|replace('a',</span> <span class="pre">'b')</span> <span class="pre">}}</span></tt> calls the function with the
value of <cite>foo</cite> as first parameter, the current context as second and
a list of filters as third. The list looks like this:</p>
<div class="syntax"><pre><span class="p">[(</span><span class="s">'escape'</span><span class="p">,</span> <span class="p">()),</span> <span class="p">(</span><span class="s">'replace'</span><span class="p">,</span> <span class="p">(</span><span class="s">u'a'</span><span class="p">,</span> <span class="s">u'b'</span><span class="p">))]</span>
</pre></div>
<p>As you can see the filter <cite>escape</cite> is called without arguments whereas
<cite>replace</cite> is called with the two literal strings <tt class="docutils literal"><span class="pre">a</span></tt> and <tt class="docutils literal"><span class="pre">b</span></tt>, both
unicode. The filters for the names are stored on <tt class="docutils literal"><span class="pre">self.filters</span></tt> in a
dict. Missing filters should raise a <cite>FilterNotFound</cite> exception.</p>
<p><strong>Warning</strong> this is a Jinja internal method. The actual implementation
and function signature might change.</p>
</blockquote>
<p><strong>def</strong> <cite>perform_test</cite> <em>(self, context, testname, args, value, invert)</em>:</p>
<blockquote>
<p>Like <cite>apply_filters</cite> you usually don't override this one. It's the
callback function for tests (<tt class="docutils literal"><span class="pre">foo</span> <span class="pre">is</span> <span class="pre">bar</span></tt> / <tt class="docutils literal"><span class="pre">foo</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">bar</span></tt>).</p>
<p>The first parameter is the current contex, the second the name of
the test to perform. the third a tuple of arguments, the fourth is
the value to test. The last one is <cite>True</cite> if the test was performed
with the <cite>is not</cite> operator, <cite>False</cite> if with the <cite>is</cite> operator.</p>
<p>Missing tests should raise a <cite>TestNotFound</cite> exception.</p>
<p><strong>Warning</strong> this is a Jinja internal method. The actual implementation
and function signature might change.</p>
</blockquote>
<p><strong>def</strong> <cite>get_attribute</cite> <em>(self, obj, attribute)</em>:</p>
<blockquote>
<p>Get <cite>attribute</cite> from the object provided. The default implementation
performs security tests.</p>
<p><strong>Warning</strong> this is a Jinja internal method. The actual implementation
and function signature might change.</p>
</blockquote>
<p><strong>def</strong> <cite>get_attributes</cite> <em>(self, obj, attributes)</em>:</p>
<blockquote>
Get some attributes from the object. If <cite>attributes</cite> is an empty
sequence the object itself is returned unchanged.</blockquote>
<p><strong>def</strong> <cite>call_function</cite> <em>(self, f, context, args, kwargs, dyn_args, dyn_kwargs)</em>:</p>
<blockquote>
<p>Call a function <cite>f</cite> with the arguments <cite>args</cite>, <cite>kwargs</cite>, <cite>dyn_args</cite> and
<cite>dyn_kwargs</cite> where <cite>args</cite> is a tuple and <cite>kwargs</cite> a dict. If <cite>dyn_args</cite>
is not <cite>None</cite> you have to add it to the arguments, if <cite>dyn_kwargs</cite> is
not <cite>None</cite> you have to update the <cite>kwargs</cite> with it.</p>
<p>The default implementation performs some security checks.</p>
<p><strong>Warning</strong> this is a Jinja internal method. The actual implementation
and function signature might change.</p>
</blockquote>
<p><strong>def</strong> <cite>call_function_simple</cite> <em>(self, f, context)</em>:</p>
<blockquote>
<p>Like <cite>call_function</cite> but without arguments.</p>
<p><strong>Warning</strong> this is a Jinja internal method. The actual implementation
and function signature might change.</p>
</blockquote>
<p><strong>def</strong> <cite>finish_var</cite> <em>(self, value, ctx)</em>:</p>
<blockquote>
<p>Postprocess a variable before it's sent to the template.</p>
<p><strong>Warning</strong> this is a Jinja internal method. The actual implementation
and function signature might change.</p>
</blockquote>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The Enviornment class is defined in <cite>jinja.environment.Environment</cite>
but imported into the <cite>jinja</cite> package because it's often used.</p>
</div>
</div>
<div class="section">
<h2><a id="context" name="context">Context</a></h2>
<p>Jinja wraps the variables passed to the template in a special class called a
context. This context supports variables on multiple layers and lazy (deferred)
objects. Often your application has a request object, database connection
object or something similar you want to access in filters, functions etc.</p>
<p>The default context object is defined in <cite>jinja.datastructure</cite>. If you want
to provide your own context object always subclass the default one. This
ensures that the class continues working after Jinja upgrades.</p>
<p>Beacause of that you can easily subclass a context to add additional variables
or to change the way it behaves.</p>
<p><strong>def</strong> <cite>pop</cite> <em>(self)</em>:</p>
<blockquote>
Pop the outermost layer and return it.</blockquote>
<p><strong>def</strong> <cite>push</cite> <em>(self, data=None)</em>:</p>
<blockquote>
<p>Push a dict to the stack or an empty layer.</p>
<p>Has to return the pushed object.</p>
</blockquote>
<p><strong>def</strong> <cite>to_dict</cite> <em>(self)</em>:</p>
<blockquote>
Flatten the context and convert it into a dict.</blockquote>
<p><strong>def</strong> <cite>__getitem__</cite> <em>(self, name)</em>:</p>
<blockquote>
Resolve an item. Per default this also resolves <cite>Deferred</cite> objects.</blockquote>
<p><strong>def</strong> <cite>__setitem__</cite> <em>(self, name, value)</em>:</p>
<blockquote>
Set an item in the outermost layer.</blockquote>
<p><strong>def</strong> <cite>__delitem__</cite> <em>(self, name)</em>:</p>
<blockquote>
Delete an item in the outermost layer. Do not raise exceptions if
the value does not exist.</blockquote>
<p><strong>def</strong> <cite>__contains__</cite> <em>(self, name)</em>:</p>
<blockquote>
Return <cite>True</cite> if <cite>name</cite> exists in the context.</blockquote>
<p><strong>attribute</strong> <cite>cache</cite>:</p>
<blockquote>
The cache is a dict which can be used by filters, test functions
and global objects to cache data. It's also used by the environment
to cache often used tests and filters.</blockquote>
<p><strong>attribute</strong> <cite>translate_func</cite>:</p>
<blockquote>
This property is created on first access and returns a translation
function used by the rendering process to translate strings with the
translator defined on the environment.</blockquote>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p>The context uses a stack of dicts internally to represent the
layers of variables. It contains at least 3 levels available on
the context with some attributes. Those are:</p>
<p><cite>globals</cite>:</p>
<blockquote>
The reference to the global namespace of the environment.
It's the lowest namespace on the stack and thus immutable</blockquote>
<p><cite>initial</cite>:</p>
<blockquote>
The initial namespace. Contains the values passed to the
context in the render function. It also contains the resolved
deferred values for bot the <cite>initial</cite> and the <cite>globals</cite>
namespace.</blockquote>
<p><cite>current</cite>:</p>
<blockquote>
The reference to the current active namespace. When the
context is initialized this automatically points to an
empty namespace.</blockquote>
<p>The number of layers on the stack are theoretically unlimited.
Some elements in the template language like loops, blocks,
macros and others push and pop the layer on entering and leaving
the section.</p>
<p>This is done in order to keep the namespace clean.</p>
<p>Note that since Jinja 1.1 the context object is a subclass of the
<cite>BaseContext</cite>, a much simpler class that just implements a stack
like namespace for python. If the <cite>_speedups</cite> extension was
compiled for jinja the base class will be
<cite>jinja._speedups.BaseContext</cite> otherwise <cite>jinja._native.BaseContext</cite>.</p>
<p>Since you cannot reproduce completely the same semantics in python
and the C API there are some things you should keep in mind:</p>
<ul class="last simple">
<li>The <cite>stack</cite> attribute of the context maps to the real layers
on the stack, thus you can modify the items but the list as
such is meant to be read only.</li>
<li><cite>globals</cite>, <cite>current</cite> and <cite>initial</cite> are read only attributes that
map to layers on the stack which you can of course modify.</li>
</ul>
</div>
</div>
<div class="section">
<h2><a id="exceptions" name="exceptions">Exceptions</a></h2>
<p>During parsing and evaluation Jinja raises a couple of Jinja specific
exceptions. All of those exceptions are defined in the <cite>jinja.exceptions</cite>
module and are subclasses of the <cite>TemplateError</cite> class defined there.</p>
<p>Here a list of exceptions that could occur:</p>
<p><cite>SecurityException</cite>:</p>
<blockquote>
<p>An exception that is raised if the template tried to access something
it should not access. In the default configuration this exception
will get caught in the Jinja rendering process and silenced.</p>
<p>If however the environment is configured to not silently fail it
could happen that this exception reaches the application.</p>
</blockquote>
<p><cite>FilterNotFound</cite>:</p>
<blockquote>
Raised if the template tried to apply a filter that does not exist.
Since this exception is a subclass of <cite>KeyError</cite> too you can catch
it this way too.</blockquote>
<p><cite>FilterArgumentError</cite>:</p>
<blockquote>
Raised if the filter received an argument that it couldn't handle.
It's a subclass of <cite>TypeError</cite> too so you can catch it this way too.</blockquote>
<p><cite>TestNotFound</cite>:</p>
<blockquote>
Raised if the template tried to perform a test that does not exist.
Since this exception is a subclass of <cite>KeyError</cite> too you can catch
it this way too.</blockquote>
<p><cite>TestArgumentError</cite>:</p>
<blockquote>
Raised if a test function received an argument that it couldn't handle.
It's a subclass of <cite>TypeError</cite> too so you can catch it this way too.</blockquote>
<p><cite>TemplateNotFound</cite>:</p>
<blockquote>
Raised if a template does not exist. Subclass of <cite>IOError</cite> too.</blockquote>
<p><cite>TemplateSyntaxError</cite>:</p>
<blockquote>
Subclass of <cite>SyntaxError</cite> and used to indicate an syntax error.</blockquote>
<p><cite>TemplateRuntimeError</cite>:</p>
<blockquote>
Generic runtime error exception which can occour at various places.</blockquote>
</div>
</div>
</div>
</body>
<!-- generated on: 2007-11-17 18:18:01.242593
file id: api -->
</html>
|
