1 # -*- coding: utf-8 -*-
6 Provides a class that holds runtime and parsing time options.
8 :copyright: (c) 2010 by the Jinja Team.
9 :license: BSD, see LICENSE for more details.
13 from jinja2 import nodes
14 from jinja2.defaults import *
15 from jinja2.lexer import get_lexer, TokenStream
16 from jinja2.parser import Parser
17 from jinja2.optimizer import optimize
18 from jinja2.compiler import generate
19 from jinja2.runtime import Undefined, new_context
20 from jinja2.exceptions import TemplateSyntaxError, TemplateNotFound, \
22 from jinja2.utils import import_string, LRUCache, Markup, missing, \
23 concat, consume, internalcode, _encode_filename
26 # for direct template usage we have up to ten living environments
27 _spontaneous_environments = LRUCache(10)
29 # the function to create jinja traceback objects. This is dynamically
30 # imported on the first exception in the exception handler.
31 _make_traceback = None
34 def get_spontaneous_environment(*args):
35 """Return a new spontaneous environment. A spontaneous environment is an
36 unnamed and unaccessible (in theory) environment that is used for
37 templates generated from a string and not from the file system.
40 env = _spontaneous_environments.get(args)
42 return Environment(*args)
45 _spontaneous_environments[args] = env = Environment(*args)
50 def create_cache(size):
51 """Return the cache class for the given size."""
59 def copy_cache(cache):
60 """Create an empty copy of the given cache."""
63 elif type(cache) is dict:
65 return LRUCache(cache.capacity)
68 def load_extensions(environment, extensions):
69 """Load the extensions from the list and bind it to the environment.
70 Returns a dict of instanciated environments.
73 for extension in extensions:
74 if isinstance(extension, basestring):
75 extension = import_string(extension)
76 result[extension.identifier] = extension(environment)
80 def _environment_sanity_check(environment):
81 """Perform a sanity check on the environment."""
82 assert issubclass(environment.undefined, Undefined), 'undefined must ' \
83 'be a subclass of undefined because filters depend on it.'
84 assert environment.block_start_string != \
85 environment.variable_start_string != \
86 environment.comment_start_string, 'block, variable and comment ' \
87 'start strings must be different'
88 assert environment.newline_sequence in ('\r', '\r\n', '\n'), \
89 'newline_sequence set to unknown line ending string.'
93 class Environment(object):
94 r"""The core component of Jinja is the `Environment`. It contains
95 important shared variables like configuration, filters, tests,
96 globals and others. Instances of this class may be modified if
97 they are not shared and if no template was loaded so far.
98 Modifications on environments after the first template was loaded
99 will lead to surprising effects and undefined behavior.
101 Here the possible initialization parameters:
104 The string marking the begin of a block. Defaults to ``'{%'``.
107 The string marking the end of a block. Defaults to ``'%}'``.
109 `variable_start_string`
110 The string marking the begin of a print statement.
111 Defaults to ``'{{'``.
113 `variable_end_string`
114 The string marking the end of a print statement. Defaults to
117 `comment_start_string`
118 The string marking the begin of a comment. Defaults to ``'{#'``.
121 The string marking the end of a comment. Defaults to ``'#}'``.
123 `line_statement_prefix`
124 If given and a string, this will be used as prefix for line based
125 statements. See also :ref:`line-statements`.
127 `line_comment_prefix`
128 If given and a string, this will be used as prefix for line based
129 based comments. See also :ref:`line-statements`.
131 .. versionadded:: 2.2
134 If this is set to ``True`` the first newline after a block is
135 removed (block, not variable tag!). Defaults to `False`.
138 The sequence that starts a newline. Must be one of ``'\r'``,
139 ``'\n'`` or ``'\r\n'``. The default is ``'\n'`` which is a
140 useful default for Linux and OS X systems as well as web
144 List of Jinja extensions to use. This can either be import paths
145 as strings or extension classes. For more information have a
146 look at :ref:`the extensions documentation <jinja-extensions>`.
149 should the optimizer be enabled? Default is `True`.
152 :class:`Undefined` or a subclass of it that is used to represent
153 undefined values in the template.
156 A callable that can be used to process the result of a variable
157 expression before it is output. For example one can convert
158 `None` implicitly into an empty string here.
161 If set to true the XML/HTML autoescaping feature is enabled by
162 default. For more details about auto escaping see
163 :class:`~jinja2.utils.Markup`. As of Jinja 2.4 this can also
164 be a callable that is passed the template name and has to
165 return `True` or `False` depending on autoescape should be
168 .. versionchanged:: 2.4
169 `autoescape` can now be a function
172 The template loader for this environment.
175 The size of the cache. Per default this is ``50`` which means
176 that if more than 50 templates are loaded the loader will clean
177 out the least recently used template. If the cache size is set to
178 ``0`` templates are recompiled all the time, if the cache size is
179 ``-1`` the cache will not be cleaned.
182 Some loaders load templates from locations where the template
183 sources may change (ie: file system or database). If
184 `auto_reload` is set to `True` (default) every time a template is
185 requested the loader checks if the source changed and if yes, it
186 will reload the template. For higher performance it's possible to
190 If set to a bytecode cache object, this object will provide a
191 cache for the internal Jinja bytecode so that templates don't
192 have to be parsed if they were not changed.
194 See :ref:`bytecode-cache` for more information.
197 #: if this environment is sandboxed. Modifying this variable won't make
198 #: the environment sandboxed though. For a real sandboxed environment
199 #: have a look at jinja2.sandbox. This flag alone controls the code
200 #: generation by the compiler.
203 #: True if the environment is just an overlay
206 #: the environment this environment is linked to if it is an overlay
209 #: shared environments have this set to `True`. A shared environment
210 #: must not be modified
213 #: these are currently EXPERIMENTAL undocumented features.
214 exception_handler = None
215 exception_formatter = None
218 block_start_string=BLOCK_START_STRING,
219 block_end_string=BLOCK_END_STRING,
220 variable_start_string=VARIABLE_START_STRING,
221 variable_end_string=VARIABLE_END_STRING,
222 comment_start_string=COMMENT_START_STRING,
223 comment_end_string=COMMENT_END_STRING,
224 line_statement_prefix=LINE_STATEMENT_PREFIX,
225 line_comment_prefix=LINE_COMMENT_PREFIX,
226 trim_blocks=TRIM_BLOCKS,
227 newline_sequence=NEWLINE_SEQUENCE,
236 bytecode_cache=None):
237 # !!Important notice!!
238 # The constructor accepts quite a few arguments that should be
239 # passed by keyword rather than position. However it's important to
240 # not change the order of arguments because it's used at least
241 # internally in those cases:
242 # - spontaneus environments (i18n extension and Template)
244 # If parameter changes are required only add parameters at the end
245 # and don't change the arguments (or the defaults!) of the arguments
248 # lexer / parser information
249 self.block_start_string = block_start_string
250 self.block_end_string = block_end_string
251 self.variable_start_string = variable_start_string
252 self.variable_end_string = variable_end_string
253 self.comment_start_string = comment_start_string
254 self.comment_end_string = comment_end_string
255 self.line_statement_prefix = line_statement_prefix
256 self.line_comment_prefix = line_comment_prefix
257 self.trim_blocks = trim_blocks
258 self.newline_sequence = newline_sequence
260 # runtime information
261 self.undefined = undefined
262 self.optimized = optimized
263 self.finalize = finalize
264 self.autoescape = autoescape
267 self.filters = DEFAULT_FILTERS.copy()
268 self.tests = DEFAULT_TESTS.copy()
269 self.globals = DEFAULT_NAMESPACE.copy()
271 # set the loader provided
273 self.bytecode_cache = None
274 self.cache = create_cache(cache_size)
275 self.bytecode_cache = bytecode_cache
276 self.auto_reload = auto_reload
279 self.extensions = load_extensions(self, extensions)
281 _environment_sanity_check(self)
283 def add_extension(self, extension):
284 """Adds an extension after the environment was created.
286 .. versionadded:: 2.5
288 self.extensions.update(load_extensions(self, [extension]))
290 def extend(self, **attributes):
291 """Add the items to the instance of the environment if they do not exist
292 yet. This is used by :ref:`extensions <writing-extensions>` to register
293 callbacks and configuration values without breaking inheritance.
295 for key, value in attributes.iteritems():
296 if not hasattr(self, key):
297 setattr(self, key, value)
299 def overlay(self, block_start_string=missing, block_end_string=missing,
300 variable_start_string=missing, variable_end_string=missing,
301 comment_start_string=missing, comment_end_string=missing,
302 line_statement_prefix=missing, line_comment_prefix=missing,
303 trim_blocks=missing, extensions=missing, optimized=missing,
304 undefined=missing, finalize=missing, autoescape=missing,
305 loader=missing, cache_size=missing, auto_reload=missing,
306 bytecode_cache=missing):
307 """Create a new overlay environment that shares all the data with the
308 current environment except of cache and the overridden attributes.
309 Extensions cannot be removed for an overlayed environment. An overlayed
310 environment automatically gets all the extensions of the environment it
311 is linked to plus optional extra extensions.
313 Creating overlays should happen after the initial environment was set
314 up completely. Not all attributes are truly linked, some are just
315 copied over so modifications on the original environment may not shine
318 args = dict(locals())
319 del args['self'], args['cache_size'], args['extensions']
321 rv = object.__new__(self.__class__)
322 rv.__dict__.update(self.__dict__)
326 for key, value in args.iteritems():
327 if value is not missing:
328 setattr(rv, key, value)
330 if cache_size is not missing:
331 rv.cache = create_cache(cache_size)
333 rv.cache = copy_cache(self.cache)
336 for key, value in self.extensions.iteritems():
337 rv.extensions[key] = value.bind(rv)
338 if extensions is not missing:
339 rv.extensions.update(load_extensions(rv, extensions))
341 return _environment_sanity_check(rv)
343 lexer = property(get_lexer, doc="The lexer for this environment.")
345 def iter_extensions(self):
346 """Iterates over the extensions by priority."""
347 return iter(sorted(self.extensions.values(),
348 key=lambda x: x.priority))
350 def getitem(self, obj, argument):
351 """Get an item or attribute of an object but prefer the item."""
354 except (TypeError, LookupError):
355 if isinstance(argument, basestring):
362 return getattr(obj, attr)
363 except AttributeError:
365 return self.undefined(obj=obj, name=argument)
367 def getattr(self, obj, attribute):
368 """Get an item or attribute of an object but prefer the attribute.
369 Unlike :meth:`getitem` the attribute *must* be a bytestring.
372 return getattr(obj, attribute)
373 except AttributeError:
376 return obj[attribute]
377 except (TypeError, LookupError, AttributeError):
378 return self.undefined(obj=obj, name=attribute)
381 def parse(self, source, name=None, filename=None):
382 """Parse the sourcecode and return the abstract syntax tree. This
383 tree of nodes is used by the compiler to convert the template into
384 executable source- or bytecode. This is useful for debugging or to
385 extract information from templates.
387 If you are :ref:`developing Jinja2 extensions <writing-extensions>`
388 this gives you a good overview of the node tree generated.
391 return self._parse(source, name, filename)
392 except TemplateSyntaxError:
393 exc_info = sys.exc_info()
394 self.handle_exception(exc_info, source_hint=source)
396 def _parse(self, source, name, filename):
397 """Internal parsing function used by `parse` and `compile`."""
398 return Parser(self, source, name, _encode_filename(filename)).parse()
400 def lex(self, source, name=None, filename=None):
401 """Lex the given sourcecode and return a generator that yields
402 tokens as tuples in the form ``(lineno, token_type, value)``.
403 This can be useful for :ref:`extension development <writing-extensions>`
404 and debugging templates.
406 This does not perform preprocessing. If you want the preprocessing
407 of the extensions to be applied you have to filter source through
408 the :meth:`preprocess` method.
410 source = unicode(source)
412 return self.lexer.tokeniter(source, name, filename)
413 except TemplateSyntaxError:
414 exc_info = sys.exc_info()
415 self.handle_exception(exc_info, source_hint=source)
417 def preprocess(self, source, name=None, filename=None):
418 """Preprocesses the source with all extensions. This is automatically
419 called for all parsing and compiling methods but *not* for :meth:`lex`
420 because there you usually only want the actual source tokenized.
422 return reduce(lambda s, e: e.preprocess(s, name, filename),
423 self.iter_extensions(), unicode(source))
425 def _tokenize(self, source, name, filename=None, state=None):
426 """Called by the parser to do the preprocessing and filtering
427 for all the extensions. Returns a :class:`~jinja2.lexer.TokenStream`.
429 source = self.preprocess(source, name, filename)
430 stream = self.lexer.tokenize(source, name, filename, state)
431 for ext in self.iter_extensions():
432 stream = ext.filter_stream(stream)
433 if not isinstance(stream, TokenStream):
434 stream = TokenStream(stream, name, filename)
437 def _generate(self, source, name, filename, defer_init=False):
438 """Internal hook that can be overriden to hook a different generate
441 .. versionadded:: 2.5
443 return generate(source, self, name, filename, defer_init=defer_init)
445 def _compile(self, source, filename):
446 """Internal hook that can be overriden to hook a different compile
449 .. versionadded:: 2.5
451 return compile(source, filename, 'exec')
454 def compile(self, source, name=None, filename=None, raw=False,
456 """Compile a node or template source code. The `name` parameter is
457 the load name of the template after it was joined using
458 :meth:`join_path` if necessary, not the filename on the file system.
459 the `filename` parameter is the estimated filename of the template on
460 the file system. If the template came from a database or memory this
463 The return value of this method is a python code object. If the `raw`
464 parameter is `True` the return value will be a string with python
465 code equivalent to the bytecode returned otherwise. This method is
466 mainly used internally.
468 `defer_init` is use internally to aid the module code generator. This
469 causes the generated code to be able to import without the global
470 environment variable to be set.
472 .. versionadded:: 2.4
473 `defer_init` parameter added.
477 if isinstance(source, basestring):
479 source = self._parse(source, name, filename)
481 source = optimize(source, self)
482 source = self._generate(source, name, filename,
483 defer_init=defer_init)
487 filename = '<template>'
489 filename = _encode_filename(filename)
490 return self._compile(source, filename)
491 except TemplateSyntaxError:
492 exc_info = sys.exc_info()
493 self.handle_exception(exc_info, source_hint=source)
495 def compile_expression(self, source, undefined_to_none=True):
496 """A handy helper method that returns a callable that accepts keyword
497 arguments that appear as variables in the expression. If called it
498 returns the result of the expression.
500 This is useful if applications want to use the same rules as Jinja
501 in template "configuration files" or similar situations.
505 >>> env = Environment()
506 >>> expr = env.compile_expression('foo == 42')
512 Per default the return value is converted to `None` if the
513 expression returns an undefined value. This can be changed
514 by setting `undefined_to_none` to `False`.
516 >>> env.compile_expression('var')() is None
518 >>> env.compile_expression('var', undefined_to_none=False)()
521 .. versionadded:: 2.1
523 parser = Parser(self, source, state='variable')
526 expr = parser.parse_expression()
527 if not parser.stream.eos:
528 raise TemplateSyntaxError('chunk after expression',
529 parser.stream.current.lineno,
531 expr.set_environment(self)
532 except TemplateSyntaxError:
533 exc_info = sys.exc_info()
534 if exc_info is not None:
535 self.handle_exception(exc_info, source_hint=source)
536 body = [nodes.Assign(nodes.Name('result', 'store'), expr, lineno=1)]
537 template = self.from_string(nodes.Template(body, lineno=1))
538 return TemplateExpression(template, undefined_to_none)
540 def compile_templates(self, target, extensions=None, filter_func=None,
541 zip='deflated', log_function=None,
542 ignore_errors=True, py_compile=False):
543 """Finds all the templates the loader can find, compiles them
544 and stores them in `target`. If `zip` is `None`, instead of in a
545 zipfile, the templates will be will be stored in a directory.
546 By default a deflate zip algorithm is used, to switch to
547 the stored algorithm, `zip` can be set to ``'stored'``.
549 `extensions` and `filter_func` are passed to :meth:`list_templates`.
550 Each template returned will be compiled to the target folder or
553 By default template compilation errors are ignored. In case a
554 log function is provided, errors are logged. If you want template
555 syntax errors to abort the compilation you can set `ignore_errors`
556 to `False` and you will get an exception on syntax errors.
558 If `py_compile` is set to `True` .pyc files will be written to the
559 target instead of standard .py files.
561 .. versionadded:: 2.4
563 from jinja2.loaders import ModuleLoader
565 if log_function is None:
566 log_function = lambda x: None
570 py_header = imp.get_magic() + \
571 u'\xff\xff\xff\xff'.encode('iso-8859-15')
573 def write_file(filename, data, mode):
575 info = ZipInfo(filename)
576 info.external_attr = 0755 << 16L
577 zip_file.writestr(info, data)
579 f = open(os.path.join(target, filename), mode)
586 from zipfile import ZipFile, ZipInfo, ZIP_DEFLATED, ZIP_STORED
587 zip_file = ZipFile(target, 'w', dict(deflated=ZIP_DEFLATED,
588 stored=ZIP_STORED)[zip])
589 log_function('Compiling into Zip archive "%s"' % target)
591 if not os.path.isdir(target):
593 log_function('Compiling into folder "%s"' % target)
596 for name in self.list_templates(extensions, filter_func):
597 source, filename, _ = self.loader.get_source(self, name)
599 code = self.compile(source, name, filename, True, True)
600 except TemplateSyntaxError, e:
601 if not ignore_errors:
603 log_function('Could not compile "%s": %s' % (name, e))
606 filename = ModuleLoader.get_module_filename(name)
609 c = self._compile(code, _encode_filename(filename))
610 write_file(filename + 'c', py_header +
611 marshal.dumps(c), 'wb')
612 log_function('Byte-compiled "%s" as %s' %
613 (name, filename + 'c'))
615 write_file(filename, code, 'w')
616 log_function('Compiled "%s" as %s' % (name, filename))
621 log_function('Finished compiling templates')
623 def list_templates(self, extensions=None, filter_func=None):
624 """Returns a list of templates for this environment. This requires
625 that the loader supports the loader's
626 :meth:`~BaseLoader.list_templates` method.
628 If there are other files in the template folder besides the
629 actual templates, the returned list can be filtered. There are two
630 ways: either `extensions` is set to a list of file extensions for
631 templates, or a `filter_func` can be provided which is a callable that
632 is passed a template name and should return `True` if it should end up
635 If the loader does not support that, a :exc:`TypeError` is raised.
637 x = self.loader.list_templates()
638 if extensions is not None:
639 if filter_func is not None:
640 raise TypeError('either extensions or filter_func '
641 'can be passed, but not both')
642 filter_func = lambda x: '.' in x and \
643 x.rsplit('.', 1)[1] in extensions
644 if filter_func is not None:
645 x = filter(filter_func, x)
648 def handle_exception(self, exc_info=None, rendered=False, source_hint=None):
649 """Exception handling helper. This is used internally to either raise
650 rewritten exceptions or return a rendered traceback for the template.
652 global _make_traceback
654 exc_info = sys.exc_info()
656 # the debugging module is imported when it's used for the first time.
657 # we're doing a lot of stuff there and for applications that do not
658 # get any exceptions in template rendering there is no need to load
660 if _make_traceback is None:
661 from jinja2.debug import make_traceback as _make_traceback
662 traceback = _make_traceback(exc_info, source_hint)
663 if rendered and self.exception_formatter is not None:
664 return self.exception_formatter(traceback)
665 if self.exception_handler is not None:
666 self.exception_handler(traceback)
667 exc_type, exc_value, tb = traceback.standard_exc_info
668 raise exc_type, exc_value, tb
670 def join_path(self, template, parent):
671 """Join a template with the parent. By default all the lookups are
672 relative to the loader root so this method returns the `template`
673 parameter unchanged, but if the paths should be relative to the
674 parent template, this function can be used to calculate the real
677 Subclasses may override this method and implement template path
683 def _load_template(self, name, globals):
684 if self.loader is None:
685 raise TypeError('no loader for this environment specified')
686 if self.cache is not None:
687 template = self.cache.get(name)
688 if template is not None and (not self.auto_reload or \
689 template.is_up_to_date):
691 template = self.loader.load(self, name, globals)
692 if self.cache is not None:
693 self.cache[name] = template
697 def get_template(self, name, parent=None, globals=None):
698 """Load a template from the loader. If a loader is configured this
699 method ask the loader for the template and returns a :class:`Template`.
700 If the `parent` parameter is not `None`, :meth:`join_path` is called
701 to get the real template name before loading.
703 The `globals` parameter can be used to provide template wide globals.
704 These variables are available in the context at render time.
706 If the template does not exist a :exc:`TemplateNotFound` exception is
709 .. versionchanged:: 2.4
710 If `name` is a :class:`Template` object it is returned from the
713 if isinstance(name, Template):
715 if parent is not None:
716 name = self.join_path(name, parent)
717 return self._load_template(name, self.make_globals(globals))
720 def select_template(self, names, parent=None, globals=None):
721 """Works like :meth:`get_template` but tries a number of templates
722 before it fails. If it cannot find any of the templates, it will
723 raise a :exc:`TemplatesNotFound` exception.
725 .. versionadded:: 2.3
727 .. versionchanged:: 2.4
728 If `names` contains a :class:`Template` object it is returned
729 from the function unchanged.
732 raise TemplatesNotFound(message=u'Tried to select from an empty list '
734 globals = self.make_globals(globals)
736 if isinstance(name, Template):
738 if parent is not None:
739 name = self.join_path(name, parent)
741 return self._load_template(name, globals)
742 except TemplateNotFound:
744 raise TemplatesNotFound(names)
747 def get_or_select_template(self, template_name_or_list,
748 parent=None, globals=None):
749 """Does a typecheck and dispatches to :meth:`select_template`
750 if an iterable of template names is given, otherwise to
751 :meth:`get_template`.
753 .. versionadded:: 2.3
755 if isinstance(template_name_or_list, basestring):
756 return self.get_template(template_name_or_list, parent, globals)
757 elif isinstance(template_name_or_list, Template):
758 return template_name_or_list
759 return self.select_template(template_name_or_list, parent, globals)
761 def from_string(self, source, globals=None, template_class=None):
762 """Load a template from a string. This parses the source given and
763 returns a :class:`Template` object.
765 globals = self.make_globals(globals)
766 cls = template_class or self.template_class
767 return cls.from_code(self, self.compile(source), globals, None)
769 def make_globals(self, d):
770 """Return a dict for the globals."""
773 return dict(self.globals, **d)
776 class Template(object):
777 """The central template object. This class represents a compiled template
778 and is used to evaluate it.
780 Normally the template object is generated from an :class:`Environment` but
781 it also has a constructor that makes it possible to create a template
782 instance directly using the constructor. It takes the same arguments as
783 the environment constructor but it's not possible to specify a loader.
785 Every template object has a few methods and members that are guaranteed
786 to exist. However it's important that a template object should be
787 considered immutable. Modifications on the object are not supported.
789 Template objects created from the constructor rather than an environment
790 do have an `environment` attribute that points to a temporary environment
791 that is probably shared with other templates created with the constructor
792 and compatible settings.
794 >>> template = Template('Hello {{ name }}!')
795 >>> template.render(name='John Doe')
798 >>> stream = template.stream(name='John Doe')
802 Traceback (most recent call last):
807 def __new__(cls, source,
808 block_start_string=BLOCK_START_STRING,
809 block_end_string=BLOCK_END_STRING,
810 variable_start_string=VARIABLE_START_STRING,
811 variable_end_string=VARIABLE_END_STRING,
812 comment_start_string=COMMENT_START_STRING,
813 comment_end_string=COMMENT_END_STRING,
814 line_statement_prefix=LINE_STATEMENT_PREFIX,
815 line_comment_prefix=LINE_COMMENT_PREFIX,
816 trim_blocks=TRIM_BLOCKS,
817 newline_sequence=NEWLINE_SEQUENCE,
823 env = get_spontaneous_environment(
824 block_start_string, block_end_string, variable_start_string,
825 variable_end_string, comment_start_string, comment_end_string,
826 line_statement_prefix, line_comment_prefix, trim_blocks,
827 newline_sequence, frozenset(extensions), optimized, undefined,
828 finalize, autoescape, None, 0, False, None)
829 return env.from_string(source, template_class=cls)
832 def from_code(cls, environment, code, globals, uptodate=None):
833 """Creates a template object from compiled code and the globals. This
834 is used by the loaders and environment to create a template object.
837 'environment': environment,
838 '__file__': code.co_filename
840 exec code in namespace
841 rv = cls._from_namespace(environment, namespace, globals)
842 rv._uptodate = uptodate
846 def from_module_dict(cls, environment, module_dict, globals):
847 """Creates a template object from a module. This is used by the
848 module loader to create a template object.
850 .. versionadded:: 2.4
852 return cls._from_namespace(environment, module_dict, globals)
855 def _from_namespace(cls, environment, namespace, globals):
856 t = object.__new__(cls)
857 t.environment = environment
859 t.name = namespace['name']
860 t.filename = namespace['__file__']
861 t.blocks = namespace['blocks']
863 # render function and module
864 t.root_render_func = namespace['root']
867 # debug and loader helpers
868 t._debug_info = namespace['debug_info']
871 # store the reference
872 namespace['environment'] = environment
873 namespace['__jinja_template__'] = t
877 def render(self, *args, **kwargs):
878 """This method accepts the same arguments as the `dict` constructor:
879 A dict, a dict subclass or some keyword arguments. If no arguments
880 are given the context will be empty. These two calls do the same::
882 template.render(knights='that say nih')
883 template.render({'knights': 'that say nih'})
885 This will return the rendered template as unicode string.
887 vars = dict(*args, **kwargs)
889 return concat(self.root_render_func(self.new_context(vars)))
891 exc_info = sys.exc_info()
892 return self.environment.handle_exception(exc_info, True)
894 def stream(self, *args, **kwargs):
895 """Works exactly like :meth:`generate` but returns a
896 :class:`TemplateStream`.
898 return TemplateStream(self.generate(*args, **kwargs))
900 def generate(self, *args, **kwargs):
901 """For very large templates it can be useful to not render the whole
902 template at once but evaluate each statement after another and yield
903 piece for piece. This method basically does exactly that and returns
904 a generator that yields one item after another as unicode strings.
906 It accepts the same arguments as :meth:`render`.
908 vars = dict(*args, **kwargs)
910 for event in self.root_render_func(self.new_context(vars)):
913 exc_info = sys.exc_info()
916 yield self.environment.handle_exception(exc_info, True)
918 def new_context(self, vars=None, shared=False, locals=None):
919 """Create a new :class:`Context` for this template. The vars
920 provided will be passed to the template. Per default the globals
921 are added to the context. If shared is set to `True` the data
922 is passed as it to the context without adding the globals.
924 `locals` can be a dict of local variables for internal usage.
926 return new_context(self.environment, self.name, self.blocks,
927 vars, shared, self.globals, locals)
929 def make_module(self, vars=None, shared=False, locals=None):
930 """This method works like the :attr:`module` attribute when called
931 without arguments but it will evaluate the template on every call
932 rather than caching it. It's also possible to provide
933 a dict which is then used as context. The arguments are the same
934 as for the :meth:`new_context` method.
936 return TemplateModule(self, self.new_context(vars, shared, locals))
940 """The template as module. This is used for imports in the
941 template runtime but is also useful if one wants to access
942 exported template variables from the Python layer:
944 >>> t = Template('{% macro foo() %}42{% endmacro %}23')
945 >>> unicode(t.module)
950 if self._module is not None:
952 self._module = rv = self.make_module()
955 def get_corresponding_lineno(self, lineno):
956 """Return the source line number of a line number in the
957 generated bytecode as they are not in sync.
959 for template_line, code_line in reversed(self.debug_info):
960 if code_line <= lineno:
965 def is_up_to_date(self):
966 """If this variable is `False` there is a newer version available."""
967 if self._uptodate is None:
969 return self._uptodate()
972 def debug_info(self):
973 """The debug info mapping."""
974 return [tuple(map(int, x.split('='))) for x in
975 self._debug_info.split('&')]
978 if self.name is None:
979 name = 'memory:%x' % id(self)
981 name = repr(self.name)
982 return '<%s %s>' % (self.__class__.__name__, name)
985 class TemplateModule(object):
986 """Represents an imported template. All the exported names of the
987 template are available as attributes on this object. Additionally
988 converting it into an unicode- or bytestrings renders the contents.
991 def __init__(self, template, context):
992 self._body_stream = list(template.root_render_func(context))
993 self.__dict__.update(context.get_exported())
994 self.__name__ = template.name
997 return Markup(concat(self._body_stream))
1000 return unicode(self).encode('utf-8')
1002 # unicode goes after __str__ because we configured 2to3 to rename
1003 # __unicode__ to __str__. because the 2to3 tree is not designed to
1004 # remove nodes from it, we leave the above __str__ around and let
1005 # it override at runtime.
1006 def __unicode__(self):
1007 return concat(self._body_stream)
1010 if self.__name__ is None:
1011 name = 'memory:%x' % id(self)
1013 name = repr(self.__name__)
1014 return '<%s %s>' % (self.__class__.__name__, name)
1017 class TemplateExpression(object):
1018 """The :meth:`jinja2.Environment.compile_expression` method returns an
1019 instance of this object. It encapsulates the expression-like access
1020 to the template with an expression it wraps.
1023 def __init__(self, template, undefined_to_none):
1024 self._template = template
1025 self._undefined_to_none = undefined_to_none
1027 def __call__(self, *args, **kwargs):
1028 context = self._template.new_context(dict(*args, **kwargs))
1029 consume(self._template.root_render_func(context))
1030 rv = context.vars['result']
1031 if self._undefined_to_none and isinstance(rv, Undefined):
1036 class TemplateStream(object):
1037 """A template stream works pretty much like an ordinary python generator
1038 but it can buffer multiple items to reduce the number of total iterations.
1039 Per default the output is unbuffered which means that for every unbuffered
1040 instruction in the template one unicode string is yielded.
1042 If buffering is enabled with a buffer size of 5, five items are combined
1043 into a new unicode string. This is mainly useful if you are streaming
1044 big templates to a client via WSGI which flushes after each iteration.
1047 def __init__(self, gen):
1049 self.disable_buffering()
1051 def dump(self, fp, encoding=None, errors='strict'):
1052 """Dump the complete stream into a file or file-like object.
1053 Per default unicode strings are written, if you want to encode
1054 before writing specifiy an `encoding`.
1058 Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
1061 if isinstance(fp, basestring):
1065 if encoding is not None:
1066 iterable = (x.encode(encoding, errors) for x in self)
1069 if hasattr(fp, 'writelines'):
1070 fp.writelines(iterable)
1072 for item in iterable:
1078 def disable_buffering(self):
1079 """Disable the output buffering."""
1080 self._next = self._gen.next
1081 self.buffered = False
1083 def enable_buffering(self, size=5):
1084 """Enable buffering. Buffer `size` items before yielding them."""
1086 raise ValueError('buffer size too small')
1088 def generator(next):
1095 while c_size < size:
1100 except StopIteration:
1107 self.buffered = True
1108 self._next = generator(self._gen.next).next
1117 # hook in default template class. if anyone reads this comment: ignore that
1118 # it's possible to use custom templates ;-)
1119 Environment.template_class = Template