Extension Class

Inheritance diagram of Extension

class Extension(environment)

Extensions can be used to add extra functionality to the Jinja template system at the parser level. Custom extensions are bound to an environment but may not store environment specific data on self. The reason for this is that an extension can be bound to another environment (for overlays) by creating a copy and reassigning the environment attribute.

As extensions are created by the environment they cannot accept any arguments for configuration. One may want to work around that by using a factory function, but that is not possible as extensions are identified by their import name. The correct way to configure the extension is storing the configuration values on the environment. Because this way the environment ends up acting as central configuration storage the attributes may clash which is why extensions have to ensure that the names they choose for configuration are not too generic. prefix for example is a terrible name, fragment_cache_prefix on the other hand is a good name as includes the name of the extension (fragment cache).

Methods

__init__(environment)
attr(name[, lineno]) Return an attribute node for the current extension.
bind(environment) Create a copy of this extension bound to another environment.
call_method(name[, args, kwargs, dyn_args, ...]) Call a method of the extension.
filter_stream(stream) It’s passed a TokenStream that can be used
parse(parser) If any of the tags matched this method is called with the parser as first argument.
preprocess(source, name[, filename]) This method is called before the actual lexing and can be used to preprocess the source.

Attributes

identifier str(object) -> string
priority int(x[, base]) -> integer
tags set() -> new empty set object

Descriptions

class Extension

Method details

__init__(environment)
attr(name, lineno=None)

Return an attribute node for the current extension. This is useful to pass constants on extensions to generated template code.

self.attr('_my_attribute', lineno=lineno)
bind(environment)

Create a copy of this extension bound to another environment.

call_method(name, args=None, kwargs=None, dyn_args=None, dyn_kwargs=None, lineno=None)

Call a method of the extension. This is a shortcut for attr() + jinja2.nodes.Call.

filter_stream(stream)

It’s passed a TokenStream that can be used to filter tokens returned. This method has to return an iterable of Tokens, but it doesn’t have to return a TokenStream.

In the ext folder of the Jinja2 source distribution there is a file called inlinegettext.py which implements a filter that utilizes this method.

parse(parser)

If any of the tags matched this method is called with the parser as first argument. The token the parser stream is pointing at is the name token that matched. This method has to return one or a list of multiple nodes.

preprocess(source, name, filename=None)

This method is called before the actual lexing and can be used to preprocess the source. The filename is optional. The return value must be the preprocessed source.

Attribute details

identifier = 'jinja2.ext.Extension'
priority = 100

the priority of that extension. This is especially useful for extensions that preprocess values. A lower value means higher priority.

New in version 2.4.

tags = set([])

if this extension parses this is the list of tags it’s listening to.

Table Of Contents

Previous topic

ExprStmtExtension Class

Next topic

ExtensionRegistry Class