Jinja
Context and Environment
The two central objects in Jinja are the Environment and Context. Both are designed to be subclassed by applications if they need to extend Jinja.
Environment
The initialization parameters are already covered in the Quickstart thus not repeated here.
But beside those configurable instance variables there are some functions used in the template evaluation code you may want to override:
def parse (source, filename):
Parse the sourcecode and return the abstract syntax tree. This tree of nodes is used by the translators to convert the template into executable source- or bytecode.
def lex (source, filename):
Tokenize the given sourcecode and return a generator of tuples in the form (lineno, token, value). The filename is just used in the exceptions raised.
New in Jinja 1.1
def from_string (source):
Load and parse a template source and translate it into eval-able Python code. This code is wrapped within a Template class that allows you to render it.
def get_template (name):
Load a template from a loader. If the template does not exist, you will get a jinja.exceptions.TemplateNotFound exception.
def to_unicode (self, value):
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.
Also None is converted into an empty string per default.
def get_translator (self, context):
Return the translator used for i18n. A translator is an object that provides the two functions gettext(string) and ngettext(singular, plural, n). Both of those functions have to behave like the ugettext and nugettext functions described in the python gettext documentation.
If you don't provide a translator a default one is used to switch between singular and plural forms.
Have a look at the i18n section for more information.
def get_translations (self, name):
Get the translations for the template name. Only works if a loader is present. See the i18n section for more details.
def get_translations_for_string (self, string):
Get the translations for the string string. 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.
def apply_filters (self, value, context, filters):
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 {{ foo|escape|replace('a', 'b') }} calls the function with the value of foo as first parameter, the current context as second and a list of filters as third. The list looks like this:
[('escape', ()), ('replace', (u'a', u'b'))]As you can see the filter escape is called without arguments whereas replace is called with the two literal strings a and b, both unicode. The filters for the names are stored on self.filters in a dict. Missing filters should raise a FilterNotFound exception.
Warning this is a Jinja internal method. The actual implementation and function signature might change.
def perform_test (self, context, testname, args, value, invert):
Like apply_filters you usually don't override this one. It's the callback function for tests (foo is bar / foo is not bar).
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 True if the test was performed with the is not operator, False if with the is operator.
Missing tests should raise a TestNotFound exception.
Warning this is a Jinja internal method. The actual implementation and function signature might change.
def get_attribute (self, obj, attribute):
Get attribute from the object provided. The default implementation performs security tests.
Warning this is a Jinja internal method. The actual implementation and function signature might change.
def get_attributes (self, obj, attributes):
Get some attributes from the object. If attributes is an empty sequence the object itself is returned unchanged.
def call_function (self, f, context, args, kwargs, dyn_args, dyn_kwargs):
Call a function f with the arguments args, kwargs, dyn_args and dyn_kwargs where args is a tuple and kwargs a dict. If dyn_args is not None you have to add it to the arguments, if dyn_kwargs is not None you have to update the kwargs with it.
The default implementation performs some security checks.
Warning this is a Jinja internal method. The actual implementation and function signature might change.
def call_function_simple (self, f, context):
Like call_function but without arguments.
Warning this is a Jinja internal method. The actual implementation and function signature might change.
def finish_var (self, value, ctx):
Postprocess a variable before it's sent to the template.
Warning this is a Jinja internal method. The actual implementation and function signature might change.
Note
The Enviornment class is defined in jinja.environment.Environment but imported into the jinja package because it's often used.
Context
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.
The default context object is defined in jinja.datastructure. If you want to provide your own context object always subclass the default one. This ensures that the class continues working after Jinja upgrades.
Beacause of that you can easily subclass a context to add additional variables or to change the way it behaves.
def pop (self):
Pop the outermost layer and return it.
def push (self, data=None):
Push a dict to the stack or an empty layer.
Has to return the pushed object.
def to_dict (self):
Flatten the context and convert it into a dict.
def __getitem__ (self, name):
Resolve an item. Per default this also resolves Deferred objects.
def __setitem__ (self, name, value):
Set an item in the outermost layer.
def __delitem__ (self, name):
Delete an item in the outermost layer. Do not raise exceptions if the value does not exist.
def __contains__ (self, name):
Return True if name exists in the context.
attribute cache:
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.
attribute translate_func:
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.
Note
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:
globals:
The reference to the global namespace of the environment. It's the lowest namespace on the stack and thus immutable
initial:
The initial namespace. Contains the values passed to the context in the render function. It also contains the resolved deferred values for bot the initial and the globals namespace.
current:
The reference to the current active namespace. When the context is initialized this automatically points to an empty namespace.
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.
This is done in order to keep the namespace clean.
Note that since Jinja 1.1 the context object is a subclass of the BaseContext, a much simpler class that just implements a stack like namespace for python. If the _speedups extension was compiled for jinja the base class will be jinja._speedups.BaseContext otherwise jinja._native.BaseContext.
Since you cannot reproduce completely the same semantics in python and the C API there are some things you should keep in mind:
- The stack 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.
- globals, current and initial are read only attributes that map to layers on the stack which you can of course modify.
Exceptions
During parsing and evaluation Jinja raises a couple of Jinja specific exceptions. All of those exceptions are defined in the jinja.exceptions module and are subclasses of the TemplateError class defined there.
Here a list of exceptions that could occur:
SecurityException:
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.
If however the environment is configured to not silently fail it could happen that this exception reaches the application.
FilterNotFound:
Raised if the template tried to apply a filter that does not exist. Since this exception is a subclass of KeyError too you can catch it this way too.
FilterArgumentError:
Raised if the filter received an argument that it couldn't handle. It's a subclass of TypeError too so you can catch it this way too.
TestNotFound:
Raised if the template tried to perform a test that does not exist. Since this exception is a subclass of KeyError too you can catch it this way too.
TestArgumentError:
Raised if a test function received an argument that it couldn't handle. It's a subclass of TypeError too so you can catch it this way too.
TemplateNotFound:
Raised if a template does not exist. Subclass of IOError too.
TemplateSyntaxError:
Subclass of SyntaxError and used to indicate an syntax error.
TemplateRuntimeError:
Generic runtime error exception which can occour at various places.