Template Class

Inheritance diagram of Template

class Template

The central template object. This class represents a compiled template and is used to evaluate it.

Normally the template object is generated from an Environment but it also has a constructor that makes it possible to create a template instance directly using the constructor. It takes the same arguments as the environment constructor but it’s not possible to specify a loader.

Every template object has a few methods and members that are guaranteed to exist. However it’s important that a template object should be considered immutable. Modifications on the object are not supported.

Template objects created from the constructor rather than an environment do have an environment attribute that points to a temporary environment that is probably shared with other templates created with the constructor and compatible settings.

>>> template = Template('Hello {{ name }}!')
>>> template.render(name='John Doe')
u'Hello John Doe!'
>>> stream = template.stream(name='John Doe')
>>> stream.next()
u'Hello John Doe!'
>>> stream.next()
Traceback (most recent call last):
    ...
StopIteration

Methods

from_code(environment, code, globals[, uptodate]) Creates a template object from compiled code and the globals.
from_module_dict(environment, module_dict, ...) Creates a template object from a module.
generate(*args, **kwargs) For very large templates it can be useful to not render the whole template at once but evaluate each statement after another and yield piece for piece.
get_corresponding_lineno(lineno) Return the source line number of a line number in the
make_module([vars, shared, locals]) This method works like the module attribute when called without arguments but it will evaluate the template on every call rather than caching it.
new_context([vars, shared, locals]) Create a new Context for this template. The vars
render(*args, **kwargs) This method accepts the same arguments as the dict constructor:
stream(*args, **kwargs) Works exactly like generate() but returns a

Attributes

debug_info The debug info mapping.
is_up_to_date If this variable is False there is a newer version available.
module The template as module.

Descriptions

class Template

Method details

classmethod from_code(environment, code, globals, uptodate=None)

Creates a template object from compiled code and the globals. This is used by the loaders and environment to create a template object.

classmethod from_module_dict(environment, module_dict, globals)

Creates a template object from a module. This is used by the module loader to create a template object.

New in version 2.4.

generate(*args, **kwargs)

For very large templates it can be useful to not render the whole template at once but evaluate each statement after another and yield piece for piece. This method basically does exactly that and returns a generator that yields one item after another as unicode strings.

It accepts the same arguments as render().

get_corresponding_lineno(lineno)

Return the source line number of a line number in the generated bytecode as they are not in sync.

make_module(vars=None, shared=False, locals=None)

This method works like the module attribute when called without arguments but it will evaluate the template on every call rather than caching it. It’s also possible to provide a dict which is then used as context. The arguments are the same as for the new_context() method.

new_context(vars=None, shared=False, locals=None)

Create a new Context for this template. The vars provided will be passed to the template. Per default the globals are added to the context. If shared is set to True the data is passed as it to the context without adding the globals.

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

render(*args, **kwargs)

This method accepts the same arguments as the dict constructor: A dict, a dict subclass or some keyword arguments. If no arguments are given the context will be empty. These two calls do the same:

template.render(knights='that say nih')
template.render({'knights': 'that say nih'})

This will return the rendered template as unicode string.

stream(*args, **kwargs)

Works exactly like generate() but returns a TemplateStream.

Attribute details

debug_info

The debug info mapping.

is_up_to_date

If this variable is False there is a newer version available.

module

The template as module. This is used for imports in the template runtime but is also useful if one wants to access exported template variables from the Python layer:

>>> t = Template('{% macro foo() %}42{% endmacro %}23')
>>> unicode(t.module)
u'23'
>>> t.module.foo()
u'42'

Table Of Contents

Previous topic

Environment Class

Next topic

TemplateExpression Class