Low Level API

The low level API exposes functionality that can be useful to understand someimplementation details, debugging purposes or advanced extension techniques. Unless you know exactly what you are doing wedon’t recommend using any of those.

• Environment.lex(source, name=None, filename=None)
• Lex the given sourcecode and return a generator that yieldstokens as tuples in the form (lineno, token_type, value).This can be useful for extension developmentand debugging templates.

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

• Environment.parse(source, name=None, filename=None)
• Parse the sourcecode and return the abstract syntax tree. Thistree of nodes is used by the compiler to convert the template intoexecutable source- or bytecode. This is useful for debugging or toextract information from templates.

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

• Environment.preprocess(source, name=None, filename=None)
• Preprocesses the source with all extensions. This is automaticallycalled for all parsing and compiling methods but not for lex()because there you usually only want the actual source tokenized.

• Template.newcontext(_vars=None, shared=False, locals=None)
• Create a new Context for this template. The varsprovided will be passed to the template. Per default the globalsare added to the context. If shared is set to True the datais passed as it to the context without adding the globals.

locals can be a dict of local variables for internal usage.

• Template.rootrender_func(_context)
• This is the low level render function. It’s passed a Contextthat has to be created by new_context() of the same template ora compatible template. This render function is generated by thecompiler from the template code and returns a generator that yieldsunicode strings.

If an exception in the template code happens the template engine willnot rewrite the exception but pass through the original one. As amatter of fact this function should only be called from within arender() / generate() / stream() call.

• Template.blocks
• A dict of block render functions. Each of these functions works exactlylike the root_render_func() with the same limitations.

• Template.is_up_to_date
• This attribute is False if there is a newer version of the templateavailable, otherwise True.

Note

The low-level API is fragile. Future Jinja2 versions will try not tochange it in a backwards incompatible way but modifications in the Jinja2core may shine through. For example if Jinja2 introduces a new AST nodein later versions that may be returned by parse().