Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 809 lines (543 sloc) 28.189 kb
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
1 API
2 ===
3
4 .. module:: jinja2
5 :synopsis: public Jinja2 API
6
7 This document describes the API to Jinja2 and not the template language. It
8 will be most useful as reference to those implementing the template interface
9 to the application and not those who are creating Jinja2 templates.
10
11 Basics
12 ------
13
14 Jinja2 uses a central object called the template :class:`Environment`.
d546358 @carldunham fixed some typos and clarifying
carldunham authored
15 Instances of this class are used to store the configuration and global objects,
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
16 and are used to load templates from the file system or other locations.
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
17 Even if you are creating templates from strings by using the constructor of
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
18 :class:`Template` class, an environment is created automatically for you,
19 albeit a shared one.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
20
21 Most applications will create one :class:`Environment` object on application
22 initialization and use that to load templates. In some cases it's however
23 useful to have multiple environments side by side, if different configurations
24 are in use.
25
26 The simplest way to configure Jinja2 to load templates for your application
27 looks roughly like this::
28
29 from jinja2 import Environment, PackageLoader
30 env = Environment(loader=PackageLoader('yourapplication', 'templates'))
31
32 This will create a template environment with the default settings and a
33 loader that looks up the templates in the `templates` folder inside the
34 `yourapplication` python package. Different loaders are available
35 and you can also write your own if you want to load templates from a
36 database or other resources.
37
38 To load a template from this environment you just have to call the
39 :meth:`get_template` method which then returns the loaded :class:`Template`::
40
41 template = env.get_template('mytemplate.html')
42
43 To render it with some variables, just call the :meth:`render` method::
44
45 print template.render(the='variables', go='here')
46
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
47 Using a template loader rather then passing strings to :class:`Template`
48 or :meth:`Environment.from_string` has multiple advantages. Besides being
49 a lot easier to use it also enables template inheritance.
50
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
51
f3c35c4 @mitsuhiko end of line sequence is no configurable
authored
52 Unicode
53 -------
54
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
55 Jinja2 is using Unicode internally which means that you have to pass Unicode
f3c35c4 @mitsuhiko end of line sequence is no configurable
authored
56 objects to the render function or bytestrings that only consist of ASCII
57 characters. Additionally newlines are normalized to one end of line
58 sequence which is per default UNIX style (``\n``).
59
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
60 Python 2.x supports two ways of representing string objects. One is the
61 `str` type and the other is the `unicode` type, both of which extend a type
62 called `basestring`. Unfortunately the default is `str` which should not
63 be used to store text based information unless only ASCII characters are
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
64 used. With Python 2.6 it is possible to make `unicode` the default on a per
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
65 module level and with Python 3 it will be the default.
66
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
67 To explicitly use a Unicode string you have to prefix the string literal
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
68 with a `u`: ``u'Hänsel und Gretel sagen Hallo'``. That way Python will
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
69 store the string as Unicode by decoding the string with the character
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
70 encoding from the current Python module. If no encoding is specified this
71 defaults to 'ASCII' which means that you can't use any non ASCII identifier.
72
73 To set a better module encoding add the following comment to the first or
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
74 second line of the Python module using the Unicode literal::
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
75
76 # -*- coding: utf-8 -*-
77
78 We recommend utf-8 as Encoding for Python modules and templates as it's
79 possible to represent every Unicode character in utf-8 and because it's
80 backwards compatible to ASCII. For Jinja2 the default encoding of templates
81 is assumed to be utf-8.
82
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
83 It is not possible to use Jinja2 to process non-Unicode data. The reason
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
84 for this is that Jinja2 uses Unicode already on the language level. For
85 example Jinja2 treats the non-breaking space as valid whitespace inside
86 expressions which requires knowledge of the encoding or operating on an
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
87 Unicode string.
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
88
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
89 For more details about Unicode in Python have a look at the excellent
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
90 `Unicode documentation`_.
91
58f351d @mitsuhiko data files are optional now
authored
92 Another important thing is how Jinja2 is handling string literals in
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
93 templates. A naive implementation would be using Unicode strings for
58f351d @mitsuhiko data files are optional now
authored
94 all string literals but it turned out in the past that this is problematic
95 as some libraries are typechecking against `str` explicitly. For example
656d5e7 @mitsuhiko Some tiny documentation fixes (unicode -> Unicode)
authored
96 `datetime.strftime` does not accept Unicode arguments. To not break it
58f351d @mitsuhiko data files are optional now
authored
97 completely Jinja2 is returning `str` for strings that fit into ASCII and
98 for everything else `unicode`:
99
100 >>> m = Template(u"{% set a, b = 'foo', 'föö' %}").module
101 >>> m.a
102 'foo'
103 >>> m.b
104 u'f\xf6\xf6'
105
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
106
107 .. _Unicode documentation: http://docs.python.org/dev/howto/unicode.html
f3c35c4 @mitsuhiko end of line sequence is no configurable
authored
108
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
109 High Level API
110 --------------
111
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
112 The high-level API is the API you will use in the application to load and
113 render Jinja2 templates. The :ref:`low-level-api` on the other side is only
114 useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
115 <jinja-extensions>`.
116
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
117 .. autoclass:: Environment([options])
31bbd9e @mitsuhiko include tags are now able to select between multiple templates
authored
118 :members: from_string, get_template, select_template,
4684498 @mitsuhiko Added missing references to docs
authored
119 get_or_select_template, join_path, extend, compile_expression,
9463850 @mitsuhiko Added add_extension method to the public API
authored
120 compile_templates, list_templates, add_extension
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
121
122 .. attribute:: shared
123
124 If a template was created by using the :class:`Template` constructor
125 an environment is created automatically. These environments are
126 created as shared environments which means that multiple templates
127 may have the same anonymous environment. For all shared environments
128 this attribute is `True`, else `False`.
129
130 .. attribute:: sandboxed
131
132 If the environment is sandboxed this attribute is `True`. For the
133 sandbox mode have a look at the documentation for the
134 :class:`~jinja2.sandbox.SandboxedEnvironment`.
135
136 .. attribute:: filters
137
138 A dict of filters for this environment. As long as no template was
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
139 loaded it's safe to add new filters or remove old. For custom filters
d1ff858 @mitsuhiko Backed out changeset 6afb554797b6, which added unicode identifier sup…
authored
140 see :ref:`writing-filters`. For valid filter names have a look at
141 :ref:`identifier-naming`.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
142
143 .. attribute:: tests
144
ad48a2e Fixed typos in documentation
Lukas Meuser authored
145 A dict of test functions for this environment. As long as no
146 template was loaded it's safe to modify this dict. For custom tests
d1ff858 @mitsuhiko Backed out changeset 6afb554797b6, which added unicode identifier sup…
authored
147 see :ref:`writing-tests`. For valid test names have a look at
148 :ref:`identifier-naming`.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
149
150 .. attribute:: globals
151
152 A dict of global variables. These variables are always available
981cbf6 @mitsuhiko removed unused imports
authored
153 in a template. As long as no template was loaded it's safe
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
154 to modify this dict. For more details see :ref:`global-namespace`.
d1ff858 @mitsuhiko Backed out changeset 6afb554797b6, which added unicode identifier sup…
authored
155 For valid object names have a look at :ref:`identifier-naming`.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
156
1493631 @ThiefMaster Let the Environment override the CodeGenerator
ThiefMaster authored
157 .. attribute:: code_generator_class
158
159 The class used for code generation. This should not be changed
160 in most cases, unless you need to modify the Python code a
161 template compiles to.
162
f22fdd5 @ThiefMaster Let the Environment override the Context
ThiefMaster authored
163 .. attribute:: context_class
164
165 The context used for templates. This should not be changed
166 in most cases, unless you need to modify internals of how
167 template variables are handled. For details, see
168 :class:`~jinja2.runtime.Context`.
169
ed98cac @mitsuhiko some documentation updates
authored
170 .. automethod:: overlay([options])
171
58f351d @mitsuhiko data files are optional now
authored
172 .. method:: undefined([hint, obj, name, exc])
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
173
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
174 Creates a new :class:`Undefined` object for `name`. This is useful
175 for filters or functions that may return undefined objects for
176 some operations. All parameters except of `hint` should be provided
177 as keyword parameters for better readability. The `hint` is used as
178 error message for the exception if provided, otherwise the error
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
179 message will be generated from `obj` and `name` automatically. The exception
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
180 provided as `exc` is raised if something with the generated undefined
181 object is done that the undefined object does not allow. The default
182 exception is :exc:`UndefinedError`. If a `hint` is provided the
972c030 @alexwlchan Fix a few small typos in the docs
alexwlchan authored
183 `name` may be omitted.
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
184
185 The most common way to create an undefined object is by providing
186 a name only::
187
188 return environment.undefined(name='some_name')
189
190 This means that the name `some_name` is not defined. If the name
191 was from an attribute of an object it makes sense to tell the
192 undefined object the holder object to improve the error message::
193
194 if not hasattr(obj, 'attr'):
195 return environment.undefined(obj=obj, name='attr')
196
197 For a more complex example you can provide a hint. For example
198 the :func:`first` filter creates an undefined object that way::
199
200 return environment.undefined('no first item, sequence was empty')
201
202 If it the `name` or `obj` is known (for example because an attribute
972c030 @alexwlchan Fix a few small typos in the docs
alexwlchan authored
203 was accessed) it should be passed to the undefined object, even if
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
204 a custom `hint` is provided. This gives undefined objects the
205 possibility to enhance the error message.
206
207 .. autoclass:: Template
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
208 :members: module, make_module
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
209
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
210 .. attribute:: globals
211
ed98cac @mitsuhiko some documentation updates
authored
212 The dict with the globals of that template. It's unsafe to modify
213 this dict as it may be shared with other templates or the environment
214 that loaded the template.
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
215
216 .. attribute:: name
217
ed98cac @mitsuhiko some documentation updates
authored
218 The loading name of the template. If the template was loaded from a
219 string this is `None`.
220
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
221 .. attribute:: filename
222
223 The filename of the template on the file system if it was loaded from
224 there. Otherwise this is `None`.
225
ed98cac @mitsuhiko some documentation updates
authored
226 .. automethod:: render([context])
227
228 .. automethod:: generate([context])
229
230 .. automethod:: stream([context])
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
231
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
232
6df604e @mitsuhiko more unittests and updated documentation for extensions. Fixed bug i…
authored
233 .. autoclass:: jinja2.environment.TemplateStream()
74b5106 @mitsuhiko Added `TemplateStream.dump`.
authored
234 :members: disable_buffering, enable_buffering, dump
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
235
236
1da23d1 @mitsuhiko autoescape no longer is a plain boolean value but can also be a function
authored
237 Autoescaping
238 ------------
239
240 .. versionadded:: 2.4
241
242 As of Jinja 2.4 the preferred way to do autoescaping is to enable the
243 :ref:`autoescape-extension` and to configure a sensible default for
244 autoescaping. This makes it possible to enable and disable autoescaping
245 on a per-template basis (HTML versus text for instance).
246
247 Here a recommended setup that enables autoescaping for templates ending
248 in ``'.html'``, ``'.htm'`` and ``'.xml'`` and disabling it by default
249 for all other extensions::
250
251 def guess_autoescape(template_name):
252 if template_name is None or '.' not in template_name:
253 return False
254 ext = template_name.rsplit('.', 1)[1]
255 return ext in ('html', 'htm', 'xml')
256
257 env = Environment(autoescape=guess_autoescape,
258 loader=PackageLoader('mypackage'),
259 extensions=['jinja2.ext.autoescape'])
260
261 When implementing a guessing autoescape function, make sure you also
262 accept `None` as valid template name. This will be passed when generating
263 templates from strings.
264
265 Inside the templates the behaviour can be temporarily changed by using
266 the `autoescape` block (see :ref:`autoescape-overrides`).
267
268
d1ff858 @mitsuhiko Backed out changeset 6afb554797b6, which added unicode identifier sup…
authored
269 .. _identifier-naming:
270
271 Notes on Identifiers
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
272 --------------------
d1ff858 @mitsuhiko Backed out changeset 6afb554797b6, which added unicode identifier sup…
authored
273
274 Jinja2 uses the regular Python 2.x naming rules. Valid identifiers have to
275 match ``[a-zA-Z_][a-zA-Z0-9_]*``. As a matter of fact non ASCII characters
276 are currently not allowed. This limitation will probably go away as soon as
277 unicode identifiers are fully specified for Python 3.
278
279 Filters and tests are looked up in separate namespaces and have slightly
280 modified identifier syntax. Filters and tests may contain dots to group
281 filters and tests by topic. For example it's perfectly valid to add a
282 function into the filter dict and call it `to.unicode`. The regular
283 expression for filter and test identifiers is
284 ``[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*```.
285
286
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
287 Undefined Types
288 ---------------
289
290 These classes can be used as undefined types. The :class:`Environment`
291 constructor takes an `undefined` parameter that can be one of those classes
292 or a custom subclass of :class:`Undefined`. Whenever the template engine is
293 unable to look up a name or access an attribute one of those objects is
294 created and returned. Some operations on undefined values are then allowed,
295 others fail.
296
297 The closest to regular Python behavior is the `StrictUndefined` which
298 disallows all operations beside testing if it's an undefined object.
299
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
300 .. autoclass:: jinja2.Undefined()
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
301
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
302 .. attribute:: _undefined_hint
303
304 Either `None` or an unicode string with the error message for
305 the undefined object.
306
307 .. attribute:: _undefined_obj
308
309 Either `None` or the owner object that caused the undefined object
310 to be created (for example because an attribute does not exist).
311
312 .. attribute:: _undefined_name
313
314 The name for the undefined variable / attribute or just `None`
315 if no such information exists.
316
317 .. attribute:: _undefined_exception
318
319 The exception that the undefined object wants to raise. This
320 is usually one of :exc:`UndefinedError` or :exc:`SecurityError`.
321
322 .. method:: _fail_with_undefined_error(\*args, \**kwargs)
323
324 When called with any arguments this method raises
325 :attr:`_undefined_exception` with an error message generated
326 from the undefined hints stored on the undefined object.
327
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
328 .. autoclass:: jinja2.DebugUndefined()
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
329
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
330 .. autoclass:: jinja2.StrictUndefined()
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
331
6e9dfbf @mitsuhiko Added tests for logging undefined and added it to the docs.
authored
332 There is also a factory function that can decorate undefined objects to
333 implement logging on failures:
334
335 .. autofunction:: jinja2.make_logging_undefined
336
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
337 Undefined objects are created by calling :attr:`undefined`.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
338
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
339 .. admonition:: Implementation
340
341 :class:`Undefined` objects are implemented by overriding the special
342 `__underscore__` methods. For example the default :class:`Undefined`
343 class implements `__unicode__` in a way that it returns an empty
344 string, however `__int__` and others still fail with an exception. To
345 allow conversion to int by returning ``0`` you can implement your own::
346
347 class NullUndefined(Undefined):
348 def __int__(self):
349 return 0
350 def __float__(self):
351 return 0.0
352
353 To disallow a method, just override it and raise
58f351d @mitsuhiko data files are optional now
authored
354 :attr:`~Undefined._undefined_exception`. Because this is a very common
355 idom in undefined objects there is the helper method
356 :meth:`~Undefined._fail_with_undefined_error` that does the error raising
357 automatically. Here a class that works like the regular :class:`Undefined`
358 but chokes on iteration::
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
359
360 class NonIterableUndefined(Undefined):
361 __iter__ = Undefined._fail_with_undefined_error
362
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
363
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
364 The Context
365 -----------
366
6df604e @mitsuhiko more unittests and updated documentation for extensions. Fixed bug i…
authored
367 .. autoclass:: jinja2.runtime.Context()
f35e281 @mitsuhiko some documentation improvements, jinja escapes " and ' now, both into…
authored
368 :members: resolve, get_exported, get_all
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
369
370 .. attribute:: parent
371
372 A dict of read only, global variables the template looks up. These
19cf9c2 @mitsuhiko small performance improvements
authored
373 can either come from another :class:`Context`, from the
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
374 :attr:`Environment.globals` or :attr:`Template.globals` or points
375 to a dict created by combining the globals with the variables
376 passed to the render function. It must not be altered.
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
377
378 .. attribute:: vars
379
380 The template local variables. This list contains environment and
381 context functions from the :attr:`parent` scope as well as local
382 modifications and exported variables from the template. The template
383 will modify this dict during template evaluation but filters and
384 context functions are not allowed to modify it.
385
386 .. attribute:: environment
387
388 The environment that loaded the template.
389
390 .. attribute:: exported_vars
391
392 This set contains all the names the template exports. The values for
393 the names are in the :attr:`vars` dict. In order to get a copy of the
394 exported variables as dict, :meth:`get_exported` can be used.
395
396 .. attribute:: name
397
398 The load name of the template owning this context.
399
400 .. attribute:: blocks
401
402 A dict with the current mapping of blocks in the template. The keys
403 in this dict are the names of the blocks, and the values a list of
404 blocks registered. The last item in each list is the current active
405 block (latest in the inheritance chain).
406
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
407 .. attribute:: eval_ctx
408
409 The current :ref:`eval-context`.
410
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
411 .. automethod:: jinja2.runtime.Context.call(callable, \*args, \**kwargs)
412
413
414 .. admonition:: Implementation
415
416 Context is immutable for the same reason Python's frame locals are
417 immutable inside functions. Both Jinja2 and Python are not using the
418 context / frame locals as data storage for variables but only as primary
419 data source.
420
421 When a template accesses a variable the template does not define, Jinja2
422 looks up the variable in the context, after that the variable is treated
423 as if it was defined in the template.
424
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
425
5cdc1ac @mitsuhiko documentation update
authored
426 .. _loaders:
427
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
428 Loaders
429 -------
430
431 Loaders are responsible for loading templates from a resource such as the
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
432 file system. The environment will keep the compiled modules in memory like
433 Python's `sys.modules`. Unlike `sys.modules` however this cache is limited in
434 size by default and templates are automatically reloaded.
cda43df @mitsuhiko updated filters: wordwraps uses the wordwrap module and urlize marks …
authored
435 All loaders are subclasses of :class:`BaseLoader`. If you want to create your
436 own loader, subclass :class:`BaseLoader` and override `get_source`.
437
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
438 .. autoclass:: jinja2.BaseLoader
cda43df @mitsuhiko updated filters: wordwraps uses the wordwrap module and urlize marks …
authored
439 :members: get_source, load
440
441 Here a list of the builtin loaders Jinja2 provides:
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
442
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
443 .. autoclass:: jinja2.FileSystemLoader
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
444
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
445 .. autoclass:: jinja2.PackageLoader
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
446
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
447 .. autoclass:: jinja2.DictLoader
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
448
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
449 .. autoclass:: jinja2.FunctionLoader
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
450
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
451 .. autoclass:: jinja2.PrefixLoader
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
452
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
453 .. autoclass:: jinja2.ChoiceLoader
454
4684498 @mitsuhiko Added missing references to docs
authored
455 .. autoclass:: jinja2.ModuleLoader
456
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
457
458 .. _bytecode-cache:
459
460 Bytecode Cache
461 --------------
462
463 Jinja 2.1 and higher support external bytecode caching. Bytecode caches make
464 it possible to store the generated bytecode on the file system or a different
465 location to avoid parsing the templates on first use.
466
467 This is especially useful if you have a web application that is initialized on
468 the first request and Jinja compiles many templates at once which slows down
469 the application.
470
3fc008b @jwilk fix a bunch of typos in the documentation
jwilk authored
471 To use a bytecode cache, instantiate it and pass it to the :class:`Environment`.
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
472
473 .. autoclass:: jinja2.BytecodeCache
474 :members: load_bytecode, dump_bytecode, clear
475
476 .. autoclass:: jinja2.bccache.Bucket
477 :members: write_bytecode, load_bytecode, bytecode_from_string,
478 bytecode_to_string, reset
479
480 .. attribute:: environment
481
482 The :class:`Environment` that created the bucket.
483
484 .. attribute:: key
485
486 The unique cache key for this bucket
487
488 .. attribute:: code
489
490 The bytecode if it's loaded, otherwise `None`.
491
492
493 Builtin bytecode caches:
494
495 .. autoclass:: jinja2.FileSystemBytecodeCache
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
496
aa1d17d @mitsuhiko Fixed bytecode cache and added support for memcached (tests still mis…
authored
497 .. autoclass:: jinja2.MemcachedBytecodeCache
498
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
499
500 Utilities
501 ---------
502
503 These helper functions and classes are useful if you add custom filters or
504 functions to a Jinja2 environment.
505
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
506 .. autofunction:: jinja2.environmentfilter
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
507
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
508 .. autofunction:: jinja2.contextfilter
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
509
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
510 .. autofunction:: jinja2.evalcontextfilter
511
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
512 .. autofunction:: jinja2.environmentfunction
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
513
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
514 .. autofunction:: jinja2.contextfunction
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
515
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
516 .. autofunction:: jinja2.evalcontextfunction
517
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
518 .. function:: escape(s)
519
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
520 Convert the characters ``&``, ``<``, ``>``, ``'``, and ``"`` in string `s`
521 to HTML-safe sequences. Use this if you need to display text that might
522 contain such characters in HTML. This function will not escaped objects
523 that do have an HTML representation such as already escaped data.
524
525 The return value is a :class:`Markup` string.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
526
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
527 .. autofunction:: jinja2.clear_caches
187bde1 @mitsuhiko added cache_clear function
authored
528
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
529 .. autofunction:: jinja2.is_undefined
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
530
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
531 .. autoclass:: jinja2.Markup([string])
58f351d @mitsuhiko data files are optional now
authored
532 :members: escape, unescape, striptags
533
534 .. admonition:: Note
535
536 The Jinja2 :class:`Markup` class is compatible with at least Pylons and
537 Genshi. It's expected that more template engines and framework will pick
538 up the `__html__` concept soon.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
539
540
541 Exceptions
542 ----------
543
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
544 .. autoexception:: jinja2.TemplateError
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
545
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
546 .. autoexception:: jinja2.UndefinedError
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
547
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
548 .. autoexception:: jinja2.TemplateNotFound
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
549
31bbd9e @mitsuhiko include tags are now able to select between multiple templates
authored
550 .. autoexception:: jinja2.TemplatesNotFound
551
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
552 .. autoexception:: jinja2.TemplateSyntaxError
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
553
f3c35c4 @mitsuhiko end of line sequence is no configurable
authored
554 .. attribute:: message
555
556 The error message as utf-8 bytestring.
557
558 .. attribute:: lineno
559
560 The line number where the error occurred
561
562 .. attribute:: name
563
564 The load name for the template as unicode string.
565
566 .. attribute:: filename
567
568 The filename that loaded the template as bytestring in the encoding
569 of the file system (most likely utf-8 or mbcs on Windows systems).
570
571 The reason why the filename and error message are bytestrings and not
572 unicode strings is that Python 2.x is not using unicode for exceptions
573 and tracebacks as well as the compiler. This will change with Python 3.
574
a816bf4 @mitsuhiko Improved bbcache and documented it.
authored
575 .. autoexception:: jinja2.TemplateAssertionError
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
576
577
578 .. _writing-filters:
579
580 Custom Filters
581 --------------
582
583 Custom filters are just regular Python functions that take the left side of
584 the filter as first argument and the the arguments passed to the filter as
585 extra arguments or keyword arguments.
586
587 For example in the filter ``{{ 42|myfilter(23) }}`` the function would be
588 called with ``myfilter(42, 23)``. Here for example a simple filter that can
589 be applied to datetime objects to format them::
590
591 def datetimeformat(value, format='%H:%M / %d-%m-%Y'):
592 return value.strftime(format)
593
594 You can register it on the template environment by updating the
595 :attr:`~Environment.filters` dict on the environment::
596
597 environment.filters['datetimeformat'] = datetimeformat
598
599 Inside the template it can then be used as follows:
600
601 .. sourcecode:: jinja
602
603 written on: {{ article.pub_date|datetimeformat }}
604 publication date: {{ article.pub_date|datetimeformat('%d-%m-%Y') }}
605
606 Filters can also be passed the current template context or environment. This
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
607 is useful if a filter wants to return an undefined value or check the current
2e3c9c7 @mitsuhiko three is the new two
authored
608 :attr:`~Environment.autoescape` setting. For this purpose three decorators
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
609 exist: :func:`environmentfilter`, :func:`contextfilter` and
610 :func:`evalcontextfilter`.
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
611
612 Here a small example filter that breaks a text into HTML line breaks and
613 paragraphs and marks the return value as safe HTML string if autoescaping is
614 enabled::
615
616 import re
449ef02 @jfinkels fixed typo in documentation: "environmentfilter" -> "evalcontextfilter"
jfinkels authored
617 from jinja2 import evalcontextfilter, Markup, escape
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
618
619 _paragraph_re = re.compile(r'(?:\r\n|\r|\n){2,}')
620
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
621 @evalcontextfilter
622 def nl2br(eval_ctx, value):
1702451 @joernhees Custom Filters example inserts escaped <br>s
joernhees authored
623 result = u'\n\n'.join(u'<p>%s</p>' % p.replace('\n', Markup('<br>\n'))
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
624 for p in _paragraph_re.split(escape(value)))
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
625 if eval_ctx.autoescape:
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
626 result = Markup(result)
627 return result
628
629 Context filters work the same just that the first argument is the current
19cf9c2 @mitsuhiko small performance improvements
authored
630 active :class:`Context` rather then the environment.
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
631
632
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
633 .. _eval-context:
634
635 Evaluation Context
636 ------------------
637
638 The evaluation context (short eval context or eval ctx) is a new object
3fc008b @jwilk fix a bunch of typos in the documentation
jwilk authored
639 introduced in Jinja 2.4 that makes it possible to activate and deactivate
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
640 compiled features at runtime.
641
642 Currently it is only used to enable and disable the automatic escaping but
643 can be used for extensions as well.
644
645 In previous Jinja versions filters and functions were marked as
646 environment callables in order to check for the autoescape status from the
647 environment. In new versions it's encouraged to check the setting from the
648 evaluation context instead.
649
650 Previous versions::
651
652 @environmentfilter
653 def filter(env, value):
654 result = do_something(value)
655 if env.autoescape:
656 result = Markup(result)
657 return result
658
659 In new versions you can either use a :func:`contextfilter` and access the
660 evaluation context from the actual context, or use a
661 :func:`evalcontextfilter` which directly passes the evaluation context to
662 the function::
663
664 @contextfilter
665 def filter(context, value):
666 result = do_something(value)
667 if context.eval_ctx.autoescape:
668 result = Markup(result)
669 return result
670
671 @evalcontextfilter
672 def filter(eval_ctx, value):
673 result = do_something(value)
674 if eval_ctx.autoescape:
675 result = Markup(result)
676 return result
677
678 The evaluation context must not be modified at runtime. Modifications
679 must only happen with a :class:`nodes.EvalContextModifier` and
680 :class:`nodes.ScopedEvalContextModifier` from an extension, not on the
681 eval context object itself.
682
76ae15e @mitsuhiko Hopefully fixed EvalContext documentation.
authored
683 .. autoclass:: jinja2.nodes.EvalContext
30fda27 @mitsuhiko More documentation updates.
authored
684
685 .. attribute:: autoescape
686
687 `True` or `False` depending on if autoescaping is active or not.
688
689 .. attribute:: volatile
690
691 `True` if the compiler cannot evaluate some expressions at compile
692 time. At runtime this should always be `False`.
693
694
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
695 .. _writing-tests:
696
697 Custom Tests
698 ------------
699
a5d8f55 @mitsuhiko filter -> test in the tests section (i feel so embarrassed).
authored
700 Tests work like filters just that there is no way for a test to get access
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
701 to the environment or context and that they can't be chained. The return
a5d8f55 @mitsuhiko filter -> test in the tests section (i feel so embarrassed).
authored
702 value of a test should be `True` or `False`. The purpose of a test is to
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
703 give the template designers the possibility to perform type and conformability
704 checks.
705
a5d8f55 @mitsuhiko filter -> test in the tests section (i feel so embarrassed).
authored
706 Here a simple test that checks if a variable is a prime number::
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
707
708 import math
709
710 def is_prime(n):
711 if n == 2:
712 return True
713 for i in xrange(2, int(math.ceil(math.sqrt(n))) + 1):
714 if n % i == 0:
715 return False
716 return True
717
718
719 You can register it on the template environment by updating the
720 :attr:`~Environment.tests` dict on the environment::
721
722 environment.tests['prime'] = is_prime
723
724 A template designer can then use the test like this:
725
726 .. sourcecode:: jinja
727
728 {% if 42 is prime %}
729 42 is a prime number
730 {% else %}
731 42 is not a prime number
732 {% endif %}
733
734
735 .. _global-namespace:
736
737 The Global Namespace
738 --------------------
739
981cbf6 @mitsuhiko removed unused imports
authored
740 Variables stored in the :attr:`Environment.globals` dict are special as they
741 are available for imported templates too, even if they are imported without
742 context. This is the place where you can put variables and functions
743 that should be available all the time. Additionally :attr:`Template.globals`
744 exist that are variables available to a specific template that are available
745 to all :meth:`~Template.render` calls.
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
746
747
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
748 .. _low-level-api:
749
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
750 Low Level API
751 -------------
752
753 The low level API exposes functionality that can be useful to understand some
754 implementation details, debugging purposes or advanced :ref:`extension
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
755 <jinja-extensions>` techniques. Unless you know exactly what you are doing we
756 don't recommend using any of those.
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
757
758 .. automethod:: Environment.lex
759
760 .. automethod:: Environment.parse
761
9ad96e7 @mitsuhiko added support for token stream filtering and preprocessing.
authored
762 .. automethod:: Environment.preprocess
763
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
764 .. automethod:: Template.new_context
765
766 .. method:: Template.root_render_func(context)
767
768 This is the low level render function. It's passed a :class:`Context`
769 that has to be created by :meth:`new_context` of the same template or
770 a compatible template. This render function is generated by the
771 compiler from the template code and returns a generator that yields
772 unicode strings.
773
774 If an exception in the template code happens the template engine will
775 not rewrite the exception but pass through the original one. As a
776 matter of fact this function should only be called from within a
777 :meth:`render` / :meth:`generate` / :meth:`stream` call.
778
779 .. attribute:: Template.blocks
780
781 A dict of block render functions. Each of these functions works exactly
782 like the :meth:`root_render_func` with the same limitations.
783
784 .. attribute:: Template.is_up_to_date
785
786 This attribute is `False` if there is a newer version of the template
787 available, otherwise `True`.
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionall…
authored
788
789 .. admonition:: Note
790
58f351d @mitsuhiko data files are optional now
authored
791 The low-level API is fragile. Future Jinja2 versions will try not to
792 change it in a backwards incompatible way but modifications in the Jinja2
793 core may shine through. For example if Jinja2 introduces a new AST node
794 in later versions that may be returned by :meth:`~Environment.parse`.
63cf9b8 @mitsuhiko Added the `meta` module.
authored
795
796 The Meta API
797 ------------
798
799 .. versionadded:: 2.2
800
801 The meta API returns some information about abstract syntax trees that
802 could help applications to implement more advanced template concepts. All
803 the functions of the meta API operate on an abstract syntax tree as
804 returned by the :meth:`Environment.parse` method.
805
806 .. autofunction:: jinja2.meta.find_undeclared_variables
807
808 .. autofunction:: jinja2.meta.find_referenced_templates
Something went wrong with that request. Please try again.