Environment Class

Inheritance diagram of Environment

class Environment(block_start_string='{%', block_end_string='%}', variable_start_string='{{', variable_end_string='}}', comment_start_string='{#', comment_end_string='#}', line_statement_prefix=None, line_comment_prefix=None, trim_blocks=False, newline_sequence='n', extensions=(), optimized=True, undefined=<class 'jinja2.runtime.Undefined'>, finalize=None, autoescape=False, loader=None, cache_size=50, auto_reload=True, bytecode_cache=None)

The core component of Jinja is the Environment. It contains important shared variables like configuration, filters, tests, globals and others. Instances of this class may be modified if they are not shared and if no template was loaded so far. Modifications on environments after the first template was loaded will lead to surprising effects and undefined behavior.

Here the possible initialization parameters:

block_start_string
The string marking the begin of a block. Defaults to '{%'.
block_end_string
The string marking the end of a block. Defaults to '%}'.
variable_start_string
The string marking the begin of a print statement. Defaults to '{{'.
variable_end_string
The string marking the end of a print statement. Defaults to '}}'.
comment_start_string
The string marking the begin of a comment. Defaults to '{#'.
comment_end_string
The string marking the end of a comment. Defaults to '#}'.
line_statement_prefix
If given and a string, this will be used as prefix for line based statements. See also line-statements.
line_comment_prefix

If given and a string, this will be used as prefix for line based based comments. See also line-statements.

New in version 2.2.

trim_blocks
If this is set to True the first newline after a block is removed (block, not variable tag!). Defaults to False.
newline_sequence
The sequence that starts a newline. Must be one of '\r', '\n' or '\r\n'. The default is '\n' which is a useful default for Linux and OS X systems as well as web applications.
extensions
List of Jinja extensions to use. This can either be import paths as strings or extension classes. For more information have a look at the extensions documentation.
optimized
should the optimizer be enabled? Default is True.
undefined
Undefined or a subclass of it that is used to represent undefined values in the template.
finalize
A callable that can be used to process the result of a variable expression before it is output. For example one can convert None implicitly into an empty string here.
autoescape

If set to true the XML/HTML autoescaping feature is enabled by default. For more details about auto escaping see Markup. As of Jinja 2.4 this can also be a callable that is passed the template name and has to return True or False depending on autoescape should be enabled by default.

Changed in version 2.4: autoescape can now be a function

loader
The template loader for this environment.
cache_size
The size of the cache. Per default this is 50 which means that if more than 50 templates are loaded the loader will clean out the least recently used template. If the cache size is set to 0 templates are recompiled all the time, if the cache size is -1 the cache will not be cleaned.
auto_reload
Some loaders load templates from locations where the template sources may change (ie: file system or database). If auto_reload is set to True (default) every time a template is requested the loader checks if the source changed and if yes, it will reload the template. For higher performance it’s possible to disable that.
bytecode_cache

If set to a bytecode cache object, this object will provide a cache for the internal Jinja bytecode so that templates don’t have to be parsed if they were not changed.

See bytecode-cache for more information.

Methods

__init__([block_start_string, ...])
add_extension(extension) Adds an extension after the environment was created.
compile(source[, name, filename, raw, ...]) Compile a node or template source code.
compile_expression(source[, undefined_to_none]) A handy helper method that returns a callable that accepts keyword arguments that appear as variables in the expression.
compile_templates(target[, extensions, ...]) Finds all the templates the loader can find, compiles them and stores them in target.
extend(**attributes) Add the items to the instance of the environment if they do not exist yet.
from_string(source[, globals, template_class]) Load a template from a string.
get_or_select_template(template_name_or_list) Does a typecheck and dispatches to select_template() if an iterable of template names is given, otherwise to get_template().
get_template(name[, parent, globals]) Load a template from the loader.
getattr(obj, attribute) Get an item or attribute of an object but prefer the attribute.
getitem(obj, argument) Get an item or attribute of an object but prefer the item.
handle_exception([exc_info, rendered, ...]) Exception handling helper.
iter_extensions() Iterates over the extensions by priority.
join_path(template, parent) Join a template with the parent.
lex(source[, name, filename]) Lex the given sourcecode and return a generator that yields tokens as tuples in the form (lineno, token_type, value).
list_templates([extensions, filter_func]) Returns a list of templates for this environment.
make_globals(d) Return a dict for the globals.
overlay([block_start_string, ...]) Create a new overlay environment that shares all the data with the current environment except of cache and the overridden attributes.
parse(source[, name, filename]) Parse the sourcecode and return the abstract syntax tree.
preprocess(source[, name, filename]) Preprocesses the source with all extensions.
select_template(names[, parent, globals]) Works like get_template() but tries a number of templates before it fails.

Attributes

exception_formatter
exception_handler
lexer The lexer for this environment.
linked_to
overlayed bool(x) -> bool
sandboxed bool(x) -> bool
shared bool(x) -> bool

Descriptions

class Environment

Method details

__init__(block_start_string='{%', block_end_string='%}', variable_start_string='{{', variable_end_string='}}', comment_start_string='{#', comment_end_string='#}', line_statement_prefix=None, line_comment_prefix=None, trim_blocks=False, newline_sequence='n', extensions=(), optimized=True, undefined=<class 'jinja2.runtime.Undefined'>, finalize=None, autoescape=False, loader=None, cache_size=50, auto_reload=True, bytecode_cache=None)
add_extension(extension)

Adds an extension after the environment was created.

New in version 2.5.

compile(source, name=None, filename=None, raw=False, defer_init=False)

Compile a node or template source code. The name parameter is the load name of the template after it was joined using join_path() if necessary, not the filename on the file system. the filename parameter is the estimated filename of the template on the file system. If the template came from a database or memory this can be omitted.

The return value of this method is a python code object. If the raw parameter is True the return value will be a string with python code equivalent to the bytecode returned otherwise. This method is mainly used internally.

defer_init is use internally to aid the module code generator. This causes the generated code to be able to import without the global environment variable to be set.

New in version 2.4: defer_init parameter added.

compile_expression(source, undefined_to_none=True)

A handy helper method that returns a callable that accepts keyword arguments that appear as variables in the expression. If called it returns the result of the expression.

This is useful if applications want to use the same rules as Jinja in template “configuration files” or similar situations.

Example usage:

>>> env = Environment()
>>> expr = env.compile_expression('foo == 42')
>>> expr(foo=23)
False
>>> expr(foo=42)
True

Per default the return value is converted to None if the expression returns an undefined value. This can be changed by setting undefined_to_none to False.

>>> env.compile_expression('var')() is None
True
>>> env.compile_expression('var', undefined_to_none=False)()
Undefined

New in version 2.1.

compile_templates(target, extensions=None, filter_func=None, zip='deflated', log_function=None, ignore_errors=True, py_compile=False)

Finds all the templates the loader can find, compiles them and stores them in target. If zip is None, instead of in a zipfile, the templates will be will be stored in a directory. By default a deflate zip algorithm is used, to switch to the stored algorithm, zip can be set to 'stored'.

extensions and filter_func are passed to list_templates(). Each template returned will be compiled to the target folder or zipfile.

By default template compilation errors are ignored. In case a log function is provided, errors are logged. If you want template syntax errors to abort the compilation you can set ignore_errors to False and you will get an exception on syntax errors.

If py_compile is set to True .pyc files will be written to the target instead of standard .py files.

New in version 2.4.

extend(**attributes)

Add the items to the instance of the environment if they do not exist yet. This is used by extensions to register callbacks and configuration values without breaking inheritance.

from_string(source, globals=None, template_class=None)

Load a template from a string. This parses the source given and returns a Template object.

get_or_select_template(template_name_or_list, parent=None, globals=None)

Does a typecheck and dispatches to select_template() if an iterable of template names is given, otherwise to get_template().

New in version 2.3.

get_template(name, parent=None, globals=None)

Load a template from the loader. If a loader is configured this method ask the loader for the template and returns a Template. If the parent parameter is not None, join_path() is called to get the real template name before loading.

The globals parameter can be used to provide template wide globals. These variables are available in the context at render time.

If the template does not exist a TemplateNotFound exception is raised.

Changed in version 2.4: If name is a Template object it is returned from the function unchanged.

getattr(obj, attribute)

Get an item or attribute of an object but prefer the attribute. Unlike getitem() the attribute must be a bytestring.

getitem(obj, argument)

Get an item or attribute of an object but prefer the item.

handle_exception(exc_info=None, rendered=False, source_hint=None)

Exception handling helper. This is used internally to either raise rewritten exceptions or return a rendered traceback for the template.

iter_extensions()

Iterates over the extensions by priority.

join_path(template, parent)

Join a template with the parent. By default all the lookups are relative to the loader root so this method returns the template parameter unchanged, but if the paths should be relative to the parent template, this function can be used to calculate the real template name.

Subclasses may override this method and implement template path joining here.

lex(source, name=None, filename=None)

Lex the given sourcecode and return a generator that yields tokens as tuples in the form (lineno, token_type, value). This can be useful for extension development and debugging templates.

This does not perform preprocessing. If you want the preprocessing of the extensions to be applied you have to filter source through the preprocess() method.

list_templates(extensions=None, filter_func=None)

Returns a list of templates for this environment. This requires that the loader supports the loader’s list_templates() method.

If there are other files in the template folder besides the actual templates, the returned list can be filtered. There are two ways: either extensions is set to a list of file extensions for templates, or a filter_func can be provided which is a callable that is passed a template name and should return True if it should end up in the result list.

If the loader does not support that, a TypeError is raised.

New in version 2.4.

make_globals(d)

Return a dict for the globals.

overlay(block_start_string=missing, block_end_string=missing, variable_start_string=missing, variable_end_string=missing, comment_start_string=missing, comment_end_string=missing, line_statement_prefix=missing, line_comment_prefix=missing, trim_blocks=missing, extensions=missing, optimized=missing, undefined=missing, finalize=missing, autoescape=missing, loader=missing, cache_size=missing, auto_reload=missing, bytecode_cache=missing)

Create a new overlay environment that shares all the data with the current environment except of cache and the overridden attributes. Extensions cannot be removed for an overlayed environment. An overlayed environment automatically gets all the extensions of the environment it is linked to plus optional extra extensions.

Creating overlays should happen after the initial environment was set up completely. Not all attributes are truly linked, some are just copied over so modifications on the original environment may not shine through.

parse(source, name=None, filename=None)

Parse the sourcecode and return the abstract syntax tree. This tree of nodes is used by the compiler to convert the template into executable source- or bytecode. This is useful for debugging or to extract information from templates.

If you are developing Jinja2 extensions this gives you a good overview of the node tree generated.

preprocess(source, name=None, filename=None)

Preprocesses the source with all extensions. This is automatically called for all parsing and compiling methods but not for lex() because there you usually only want the actual source tokenized.

select_template(names, parent=None, globals=None)

Works like get_template() but tries a number of templates before it fails. If it cannot find any of the templates, it will raise a TemplatesNotFound exception.

New in version 2.3.

Changed in version 2.4: If names contains a Template object it is returned from the function unchanged.

Attribute details

exception_formatter = None
exception_handler = None

these are currently EXPERIMENTAL undocumented features.

lexer

The lexer for this environment.

linked_to = None

the environment this environment is linked to if it is an overlay

overlayed = False

True if the environment is just an overlay

sandboxed = False

if this environment is sandboxed. Modifying this variable won’t make the environment sandboxed though. For a real sandboxed environment have a look at jinja2.sandbox. This flag alone controls the code generation by the compiler.

shared = False

shared environments have this set to True. A shared environment must not be modified

Table Of Contents

Previous topic

load_extensions

Next topic

Template Class