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 instantiated 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 # - spontaneous 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 overridden 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 overridden 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 # Python 3.3 added a source filesize to the header
574 if sys.version_info >= (3, 3):
575 py_header += '\x00\x00\x00\x00'
577 def write_file(filename, data, mode):
579 info = ZipInfo(filename)
580 info.external_attr = 0755 << 16L
581 zip_file.writestr(info, data)
583 f = open(os.path.join(target, filename), mode)
590 from zipfile import ZipFile, ZipInfo, ZIP_DEFLATED, ZIP_STORED
591 zip_file = ZipFile(target, 'w', dict(deflated=ZIP_DEFLATED,
592 stored=ZIP_STORED)[zip])
593 log_function('Compiling into Zip archive "%s"' % target)
595 if not os.path.isdir(target):
597 log_function('Compiling into folder "%s"' % target)
600 for name in self.list_templates(extensions, filter_func):
601 source, filename, _ = self.loader.get_source(self, name)
603 code = self.compile(source, name, filename, True, True)
604 except TemplateSyntaxError, e:
605 if not ignore_errors:
607 log_function('Could not compile "%s": %s' % (name, e))
610 filename = ModuleLoader.get_module_filename(name)
613 c = self._compile(code, _encode_filename(filename))
614 write_file(filename + 'c', py_header +
615 marshal.dumps(c), 'wb')
616 log_function('Byte-compiled "%s" as %s' %
617 (name, filename + 'c'))
619 write_file(filename, code, 'w')
620 log_function('Compiled "%s" as %s' % (name, filename))
625 log_function('Finished compiling templates')
627 def list_templates(self, extensions=None, filter_func=None):
628 """Returns a list of templates for this environment. This requires
629 that the loader supports the loader's
630 :meth:`~BaseLoader.list_templates` method.
632 If there are other files in the template folder besides the
633 actual templates, the returned list can be filtered. There are two
634 ways: either `extensions` is set to a list of file extensions for
635 templates, or a `filter_func` can be provided which is a callable that
636 is passed a template name and should return `True` if it should end up
639 If the loader does not support that, a :exc:`TypeError` is raised.
641 .. versionadded:: 2.4
643 x = self.loader.list_templates()
644 if extensions is not None:
645 if filter_func is not None:
646 raise TypeError('either extensions or filter_func '
647 'can be passed, but not both')
648 filter_func = lambda x: '.' in x and \
649 x.rsplit('.', 1)[1] in extensions
650 if filter_func is not None:
651 x = filter(filter_func, x)
654 def handle_exception(self, exc_info=None, rendered=False, source_hint=None):
655 """Exception handling helper. This is used internally to either raise
656 rewritten exceptions or return a rendered traceback for the template.
658 global _make_traceback
660 exc_info = sys.exc_info()
662 # the debugging module is imported when it's used for the first time.
663 # we're doing a lot of stuff there and for applications that do not
664 # get any exceptions in template rendering there is no need to load
666 if _make_traceback is None:
667 from jinja2.debug import make_traceback as _make_traceback
668 traceback = _make_traceback(exc_info, source_hint)
669 if rendered and self.exception_formatter is not None:
670 return self.exception_formatter(traceback)
671 if self.exception_handler is not None:
672 self.exception_handler(traceback)
673 exc_type, exc_value, tb = traceback.standard_exc_info
674 raise exc_type, exc_value, tb
676 def join_path(self, template, parent):
677 """Join a template with the parent. By default all the lookups are
678 relative to the loader root so this method returns the `template`
679 parameter unchanged, but if the paths should be relative to the
680 parent template, this function can be used to calculate the real
683 Subclasses may override this method and implement template path
689 def _load_template(self, name, globals):
690 if self.loader is None:
691 raise TypeError('no loader for this environment specified')
692 if self.cache is not None:
693 template = self.cache.get(name)
694 if template is not None and (not self.auto_reload or \
695 template.is_up_to_date):
697 template = self.loader.load(self, name, globals)
698 if self.cache is not None:
699 self.cache[name] = template
703 def get_template(self, name, parent=None, globals=None):
704 """Load a template from the loader. If a loader is configured this
705 method ask the loader for the template and returns a :class:`Template`.
706 If the `parent` parameter is not `None`, :meth:`join_path` is called
707 to get the real template name before loading.
709 The `globals` parameter can be used to provide template wide globals.
710 These variables are available in the context at render time.
712 If the template does not exist a :exc:`TemplateNotFound` exception is
715 .. versionchanged:: 2.4
716 If `name` is a :class:`Template` object it is returned from the
719 if isinstance(name, Template):
721 if parent is not None:
722 name = self.join_path(name, parent)
723 return self._load_template(name, self.make_globals(globals))
726 def select_template(self, names, parent=None, globals=None):
727 """Works like :meth:`get_template` but tries a number of templates
728 before it fails. If it cannot find any of the templates, it will
729 raise a :exc:`TemplatesNotFound` exception.
731 .. versionadded:: 2.3
733 .. versionchanged:: 2.4
734 If `names` contains a :class:`Template` object it is returned
735 from the function unchanged.
738 raise TemplatesNotFound(message=u'Tried to select from an empty list '
740 globals = self.make_globals(globals)
742 if isinstance(name, Template):
744 if parent is not None:
745 name = self.join_path(name, parent)
747 return self._load_template(name, globals)
748 except TemplateNotFound:
750 raise TemplatesNotFound(names)
753 def get_or_select_template(self, template_name_or_list,
754 parent=None, globals=None):
755 """Does a typecheck and dispatches to :meth:`select_template`
756 if an iterable of template names is given, otherwise to
757 :meth:`get_template`.
759 .. versionadded:: 2.3
761 if isinstance(template_name_or_list, basestring):
762 return self.get_template(template_name_or_list, parent, globals)
763 elif isinstance(template_name_or_list, Template):
764 return template_name_or_list
765 return self.select_template(template_name_or_list, parent, globals)
767 def from_string(self, source, globals=None, template_class=None):
768 """Load a template from a string. This parses the source given and
769 returns a :class:`Template` object.
771 globals = self.make_globals(globals)
772 cls = template_class or self.template_class
773 return cls.from_code(self, self.compile(source), globals, None)
775 def make_globals(self, d):
776 """Return a dict for the globals."""
779 return dict(self.globals, **d)
782 class Template(object):
783 """The central template object. This class represents a compiled template
784 and is used to evaluate it.
786 Normally the template object is generated from an :class:`Environment` but
787 it also has a constructor that makes it possible to create a template
788 instance directly using the constructor. It takes the same arguments as
789 the environment constructor but it's not possible to specify a loader.
791 Every template object has a few methods and members that are guaranteed
792 to exist. However it's important that a template object should be
793 considered immutable. Modifications on the object are not supported.
795 Template objects created from the constructor rather than an environment
796 do have an `environment` attribute that points to a temporary environment
797 that is probably shared with other templates created with the constructor
798 and compatible settings.
800 >>> template = Template('Hello {{ name }}!')
801 >>> template.render(name='John Doe')
804 >>> stream = template.stream(name='John Doe')
808 Traceback (most recent call last):
813 def __new__(cls, source,
814 block_start_string=BLOCK_START_STRING,
815 block_end_string=BLOCK_END_STRING,
816 variable_start_string=VARIABLE_START_STRING,
817 variable_end_string=VARIABLE_END_STRING,
818 comment_start_string=COMMENT_START_STRING,
819 comment_end_string=COMMENT_END_STRING,
820 line_statement_prefix=LINE_STATEMENT_PREFIX,
821 line_comment_prefix=LINE_COMMENT_PREFIX,
822 trim_blocks=TRIM_BLOCKS,
823 newline_sequence=NEWLINE_SEQUENCE,
829 env = get_spontaneous_environment(
830 block_start_string, block_end_string, variable_start_string,
831 variable_end_string, comment_start_string, comment_end_string,
832 line_statement_prefix, line_comment_prefix, trim_blocks,
833 newline_sequence, frozenset(extensions), optimized, undefined,
834 finalize, autoescape, None, 0, False, None)
835 return env.from_string(source, template_class=cls)
838 def from_code(cls, environment, code, globals, uptodate=None):
839 """Creates a template object from compiled code and the globals. This
840 is used by the loaders and environment to create a template object.
843 'environment': environment,
844 '__file__': code.co_filename
846 exec code in namespace
847 rv = cls._from_namespace(environment, namespace, globals)
848 rv._uptodate = uptodate
852 def from_module_dict(cls, environment, module_dict, globals):
853 """Creates a template object from a module. This is used by the
854 module loader to create a template object.
856 .. versionadded:: 2.4
858 return cls._from_namespace(environment, module_dict, globals)
861 def _from_namespace(cls, environment, namespace, globals):
862 t = object.__new__(cls)
863 t.environment = environment
865 t.name = namespace['name']
866 t.filename = namespace['__file__']
867 t.blocks = namespace['blocks']
869 # render function and module
870 t.root_render_func = namespace['root']
873 # debug and loader helpers
874 t._debug_info = namespace['debug_info']
877 # store the reference
878 namespace['environment'] = environment
879 namespace['__jinja_template__'] = t
883 def render(self, *args, **kwargs):
884 """This method accepts the same arguments as the `dict` constructor:
885 A dict, a dict subclass or some keyword arguments. If no arguments
886 are given the context will be empty. These two calls do the same::
888 template.render(knights='that say nih')
889 template.render({'knights': 'that say nih'})
891 This will return the rendered template as unicode string.
893 vars = dict(*args, **kwargs)
895 return concat(self.root_render_func(self.new_context(vars)))
897 exc_info = sys.exc_info()
898 return self.environment.handle_exception(exc_info, True)
900 def stream(self, *args, **kwargs):
901 """Works exactly like :meth:`generate` but returns a
902 :class:`TemplateStream`.
904 return TemplateStream(self.generate(*args, **kwargs))
906 def generate(self, *args, **kwargs):
907 """For very large templates it can be useful to not render the whole
908 template at once but evaluate each statement after another and yield
909 piece for piece. This method basically does exactly that and returns
910 a generator that yields one item after another as unicode strings.
912 It accepts the same arguments as :meth:`render`.
914 vars = dict(*args, **kwargs)
916 for event in self.root_render_func(self.new_context(vars)):
919 exc_info = sys.exc_info()
922 yield self.environment.handle_exception(exc_info, True)
924 def new_context(self, vars=None, shared=False, locals=None):
925 """Create a new :class:`Context` for this template. The vars
926 provided will be passed to the template. Per default the globals
927 are added to the context. If shared is set to `True` the data
928 is passed as it to the context without adding the globals.
930 `locals` can be a dict of local variables for internal usage.
932 return new_context(self.environment, self.name, self.blocks,
933 vars, shared, self.globals, locals)
935 def make_module(self, vars=None, shared=False, locals=None):
936 """This method works like the :attr:`module` attribute when called
937 without arguments but it will evaluate the template on every call
938 rather than caching it. It's also possible to provide
939 a dict which is then used as context. The arguments are the same
940 as for the :meth:`new_context` method.
942 return TemplateModule(self, self.new_context(vars, shared, locals))
946 """The template as module. This is used for imports in the
947 template runtime but is also useful if one wants to access
948 exported template variables from the Python layer:
950 >>> t = Template('{% macro foo() %}42{% endmacro %}23')
951 >>> unicode(t.module)
956 if self._module is not None:
958 self._module = rv = self.make_module()
961 def get_corresponding_lineno(self, lineno):
962 """Return the source line number of a line number in the
963 generated bytecode as they are not in sync.
965 for template_line, code_line in reversed(self.debug_info):
966 if code_line <= lineno:
971 def is_up_to_date(self):
972 """If this variable is `False` there is a newer version available."""
973 if self._uptodate is None:
975 return self._uptodate()
978 def debug_info(self):
979 """The debug info mapping."""
980 return [tuple(map(int, x.split('='))) for x in
981 self._debug_info.split('&')]
984 if self.name is None:
985 name = 'memory:%x' % id(self)
987 name = repr(self.name)
988 return '<%s %s>' % (self.__class__.__name__, name)
991 class TemplateModule(object):
992 """Represents an imported template. All the exported names of the
993 template are available as attributes on this object. Additionally
994 converting it into an unicode- or bytestrings renders the contents.
997 def __init__(self, template, context):
998 self._body_stream = list(template.root_render_func(context))
999 self.__dict__.update(context.get_exported())
1000 self.__name__ = template.name
1003 return Markup(concat(self._body_stream))
1006 return unicode(self).encode('utf-8')
1008 # unicode goes after __str__ because we configured 2to3 to rename
1009 # __unicode__ to __str__. because the 2to3 tree is not designed to
1010 # remove nodes from it, we leave the above __str__ around and let
1011 # it override at runtime.
1012 def __unicode__(self):
1013 return concat(self._body_stream)
1016 if self.__name__ is None:
1017 name = 'memory:%x' % id(self)
1019 name = repr(self.__name__)
1020 return '<%s %s>' % (self.__class__.__name__, name)
1023 class TemplateExpression(object):
1024 """The :meth:`jinja2.Environment.compile_expression` method returns an
1025 instance of this object. It encapsulates the expression-like access
1026 to the template with an expression it wraps.
1029 def __init__(self, template, undefined_to_none):
1030 self._template = template
1031 self._undefined_to_none = undefined_to_none
1033 def __call__(self, *args, **kwargs):
1034 context = self._template.new_context(dict(*args, **kwargs))
1035 consume(self._template.root_render_func(context))
1036 rv = context.vars['result']
1037 if self._undefined_to_none and isinstance(rv, Undefined):
1042 class TemplateStream(object):
1043 """A template stream works pretty much like an ordinary python generator
1044 but it can buffer multiple items to reduce the number of total iterations.
1045 Per default the output is unbuffered which means that for every unbuffered
1046 instruction in the template one unicode string is yielded.
1048 If buffering is enabled with a buffer size of 5, five items are combined
1049 into a new unicode string. This is mainly useful if you are streaming
1050 big templates to a client via WSGI which flushes after each iteration.
1053 def __init__(self, gen):
1055 self.disable_buffering()
1057 def dump(self, fp, encoding=None, errors='strict'):
1058 """Dump the complete stream into a file or file-like object.
1059 Per default unicode strings are written, if you want to encode
1060 before writing specify an `encoding`.
1064 Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
1067 if isinstance(fp, basestring):
1071 if encoding is not None:
1072 iterable = (x.encode(encoding, errors) for x in self)
1075 if hasattr(fp, 'writelines'):
1076 fp.writelines(iterable)
1078 for item in iterable:
1084 def disable_buffering(self):
1085 """Disable the output buffering."""
1086 self._next = self._gen.next
1087 self.buffered = False
1089 def enable_buffering(self, size=5):
1090 """Enable buffering. Buffer `size` items before yielding them."""
1092 raise ValueError('buffer size too small')
1094 def generator(next):
1101 while c_size < size:
1106 except StopIteration:
1113 self.buffered = True
1114 self._next = generator(self._gen.next).next
1123 # hook in default template class. if anyone reads this comment: ignore that
1124 # it's possible to use custom templates ;-)
1125 Environment.template_class = Template