5 :synopsis: public Jinja2 API
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.
14 Jinja2 uses a central object called the template :class:`Environment`.
15 Instances of this class are used to store the configuration, global objects
16 and are used to load templates from the file system or other locations.
17 Even if you are creating templates from string by using the constructor of
18 :class:`Template` class, an environment is created automatically for you.
20 Most applications will create one :class:`Environment` object on application
21 initialization and use that to load templates. In some cases it's however
22 useful to have multiple environments side by side, if different configurations
25 The simplest way to configure Jinja2 to load templates for your application
26 looks roughly like this::
28 from jinja2 import Environment, PackageLoader
29 env = Environment(loader=PackageLoader('yourapplication', 'templates'))
31 This will create a template environment with the default settings and a
32 loader that looks up the templates in the `templates` folder inside the
33 `yourapplication` python package. Different loaders are available
34 and you can also write your own if you want to load templates from a
35 database or other resources.
37 To load a template from this environment you just have to call the
38 :meth:`get_template` method which then returns the loaded :class:`Template`::
40 template = env.get_template('mytemplate.html')
42 To render it with some variables, just call the :meth:`render` method::
44 print template.render(the='variables', go='here')
50 .. autoclass:: jinja2.environment.Environment([options])
51 :members: from_string, get_template, join_path, parse, lex, extend
55 If a template was created by using the :class:`Template` constructor
56 an environment is created automatically. These environments are
57 created as shared environments which means that multiple templates
58 may have the same anonymous environment. For all shared environments
59 this attribute is `True`, else `False`.
61 .. attribute:: sandboxed
63 If the environment is sandboxed this attribute is `True`. For the
64 sandbox mode have a look at the documentation for the
65 :class:`~jinja2.sandbox.SandboxedEnvironment`.
67 .. attribute:: filters
69 A dict of filters for this environment. As long as no template was
70 loaded it's safe to add new filters or remove old. For custom filters
71 see :ref:`writing-filters`. For valid filter names have a look at
72 :ref:`identifier-naming`.
76 A dict of test functions for this environment. As long as no
77 template was loaded it's safe to modify this dict. For custom tests
78 see :ref:`writing-tests`. For valid test names have a look at
79 :ref:`identifier-naming`.
81 .. attribute:: globals
83 A dict of global variables. These variables are always available
84 in a template. As long as no template was loaded it's safe
85 to modify this dict. For more details see :ref:`global-namespace`.
86 For valid object names have a look at :ref:`identifier-naming`.
88 .. automethod:: overlay([options])
91 .. autoclass:: jinja2.Template
92 :members: make_module, module, new_context
94 .. attribute:: globals
96 The dict with the globals of that template. It's unsafe to modify
97 this dict as it may be shared with other templates or the environment
98 that loaded the template.
102 The loading name of the template. If the template was loaded from a
103 string this is `None`.
105 .. automethod:: render([context])
107 .. automethod:: generate([context])
109 .. automethod:: stream([context])
112 .. autoclass:: jinja2.environment.TemplateStream
113 :members: disable_buffering, enable_buffering
116 .. _identifier-naming:
121 Jinja2 uses the regular Python 2.x naming rules. Valid identifiers have to
122 match ``[a-zA-Z_][a-zA-Z0-9_]*``. As a matter of fact non ASCII characters
123 are currently not allowed. This limitation will probably go away as soon as
124 unicode identifiers are fully specified for Python 3.
126 Filters and tests are looked up in separate namespaces and have slightly
127 modified identifier syntax. Filters and tests may contain dots to group
128 filters and tests by topic. For example it's perfectly valid to add a
129 function into the filter dict and call it `to.unicode`. The regular
130 expression for filter and test identifiers is
131 ``[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*```.
137 These classes can be used as undefined types. The :class:`Environment`
138 constructor takes an `undefined` parameter that can be one of those classes
139 or a custom subclass of :class:`Undefined`. Whenever the template engine is
140 unable to look up a name or access an attribute one of those objects is
141 created and returned. Some operations on undefined values are then allowed,
144 The closest to regular Python behavior is the `StrictUndefined` which
145 disallows all operations beside testing if it's an undefined object.
147 .. autoclass:: jinja2.runtime.Undefined
149 .. autoclass:: jinja2.runtime.DebugUndefined
151 .. autoclass:: jinja2.runtime.StrictUndefined
157 .. autoclass:: jinja2.runtime.Context
158 :members: resolve, get_exported, get_all
160 .. attribute:: parent
162 A dict of read only, global variables the template looks up. These
163 can either come from another :class:`Context`, from the
164 :attr:`Environment.globals` or :attr:`Template.globals`. It must not
169 The template local variables. This list contains environment and
170 context functions from the :attr:`parent` scope as well as local
171 modifications and exported variables from the template. The template
172 will modify this dict during template evaluation but filters and
173 context functions are not allowed to modify it.
175 .. attribute:: environment
177 The environment that loaded the template.
179 .. attribute:: exported_vars
181 This set contains all the names the template exports. The values for
182 the names are in the :attr:`vars` dict. In order to get a copy of the
183 exported variables as dict, :meth:`get_exported` can be used.
187 The load name of the template owning this context.
189 .. attribute:: blocks
191 A dict with the current mapping of blocks in the template. The keys
192 in this dict are the names of the blocks, and the values a list of
193 blocks registered. The last item in each list is the current active
194 block (latest in the inheritance chain).
202 Loaders are responsible for loading templates from a resource such as the
203 file system. The environment will keep the compiled modules in memory like
204 Python's `sys.modules`. Unlike `sys.modules` however this cache is limited in
205 size by default and templates are automatically reloaded.
206 All loaders are subclasses of :class:`BaseLoader`. If you want to create your
207 own loader, subclass :class:`BaseLoader` and override `get_source`.
209 .. autoclass:: jinja2.loaders.BaseLoader
210 :members: get_source, load
212 Here a list of the builtin loaders Jinja2 provides:
214 .. autoclass:: jinja2.loaders.FileSystemLoader
216 .. autoclass:: jinja2.loaders.PackageLoader
218 .. autoclass:: jinja2.loaders.DictLoader
220 .. autoclass:: jinja2.loaders.FunctionLoader
222 .. autoclass:: jinja2.loaders.PrefixLoader
224 .. autoclass:: jinja2.loaders.ChoiceLoader
230 These helper functions and classes are useful if you add custom filters or
231 functions to a Jinja2 environment.
233 .. autofunction:: jinja2.filters.environmentfilter
235 .. autofunction:: jinja2.filters.contextfilter
237 .. autofunction:: jinja2.utils.environmentfunction
239 .. autofunction:: jinja2.utils.contextfunction
241 .. function:: escape(s)
243 Convert the characters &, <, >, and " in string s to HTML-safe sequences.
244 Use this if you need to display text that might contain such characters
245 in HTML. This function will not escaped objects that do have an HTML
246 representation such as already escaped data.
248 .. autofunction:: jinja2.utils.clear_caches
250 .. autoclass:: jinja2.utils.Markup
256 .. autoexception:: jinja2.exceptions.TemplateError
258 .. autoexception:: jinja2.exceptions.UndefinedError
260 .. autoexception:: jinja2.exceptions.TemplateNotFound
262 .. autoexception:: jinja2.exceptions.TemplateSyntaxError
264 .. autoexception:: jinja2.exceptions.TemplateAssertionError
272 Custom filters are just regular Python functions that take the left side of
273 the filter as first argument and the the arguments passed to the filter as
274 extra arguments or keyword arguments.
276 For example in the filter ``{{ 42|myfilter(23) }}`` the function would be
277 called with ``myfilter(42, 23)``. Here for example a simple filter that can
278 be applied to datetime objects to format them::
280 def datetimeformat(value, format='%H:%M / %d-%m-%Y'):
281 return value.strftime(format)
283 You can register it on the template environment by updating the
284 :attr:`~Environment.filters` dict on the environment::
286 environment.filters['datetimeformat'] = datetimeformat
288 Inside the template it can then be used as follows:
290 .. sourcecode:: jinja
292 written on: {{ article.pub_date|datetimeformat }}
293 publication date: {{ article.pub_date|datetimeformat('%d-%m-%Y') }}
295 Filters can also be passed the current template context or environment. This
296 is useful if a filters wants to return an undefined value or check the current
297 :attr:`~Environment.autoescape` setting. For this purpose two decorators
298 exist: :func:`environmentfilter` and :func:`contextfilter`.
300 Here a small example filter that breaks a text into HTML line breaks and
301 paragraphs and marks the return value as safe HTML string if autoescaping is
305 from jinja2 import environmentfilter, Markup, escape
307 _paragraph_re = re.compile(r'(?:\r\n|\r|\n){2,}')
310 def nl2br(environment, value):
311 result = u'\n\n'.join(u'<p>%s</p>' % p.replace('\n', '<br>\n')
312 for p in _paragraph_re.split(escape(value)))
313 if environment.autoescape:
314 result = Markup(result)
317 Context filters work the same just that the first argument is the current
318 active :class:`Context` rather then the environment.
326 Tests work like filters just that there is no way for a filter to get access
327 to the environment or context and that they can't be chained. The return
328 value of a filter should be `True` or `False`. The purpose of a filter is to
329 give the template designers the possibility to perform type and conformability
332 Here a simple filter that checks if a variable is a prime number::
339 for i in xrange(2, int(math.ceil(math.sqrt(n))) + 1):
345 You can register it on the template environment by updating the
346 :attr:`~Environment.tests` dict on the environment::
348 environment.tests['prime'] = is_prime
350 A template designer can then use the test like this:
352 .. sourcecode:: jinja
357 42 is not a prime number
361 .. _global-namespace:
366 Variables stored in the :attr:`Environment.globals` dict are special as they
367 are available for imported templates too, even if they are imported without
368 context. This is the place where you can put variables and functions
369 that should be available all the time. Additionally :attr:`Template.globals`
370 exist that are variables available to a specific template that are available
371 to all :meth:`~Template.render` calls.
377 Jinja2 behaves like regular Python code in the runtime with some additional
378 restrictions that allow the template engine to optimize some common idoms.
379 The context is semi immutable. Only Jinja2 itself may modify it, if other
380 code (such as :func:`contextfunction`\s) modify it the changes won't show up
383 Another change to regular Python is that Jinja2 sees attributes as immutable.
384 It assumes that every time it accesses `foo.bar`, bar will look the same as
385 long as `foo` was not overriden. In some situations Jinja will take advantage
386 of that to internally substitute continuous lookups to the same attributes
387 with a copy of the attribute.
389 For example in the following template the `post.user` attribute is looked up
392 .. sourcecode:: html+jinja
395 <h3>{{ post.user.username }}</h3>
396 <p>Location: {{ post.user.location }}</p>
399 That said, the objects passed to the template may not generate different
400 values every time a property is accessed.