1b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)# -*- coding: utf-8 -*- 2b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)""" 3b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) jinja2.environment 4b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ~~~~~~~~~~~~~~~~~~ 5b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 6b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Provides a class that holds runtime and parsing time options. 7b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 8b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :copyright: (c) 2010 by the Jinja Team. 9b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :license: BSD, see LICENSE for more details. 10b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)""" 11b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)import os 12b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)import sys 13b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2 import nodes 1458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)from jinja2.defaults import BLOCK_START_STRING, \ 1558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) BLOCK_END_STRING, VARIABLE_START_STRING, VARIABLE_END_STRING, \ 1658537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) COMMENT_START_STRING, COMMENT_END_STRING, LINE_STATEMENT_PREFIX, \ 1758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) LINE_COMMENT_PREFIX, TRIM_BLOCKS, NEWLINE_SEQUENCE, \ 1858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) DEFAULT_FILTERS, DEFAULT_TESTS, DEFAULT_NAMESPACE, \ 1958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) KEEP_TRAILING_NEWLINE, LSTRIP_BLOCKS 20b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2.lexer import get_lexer, TokenStream 21b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2.parser import Parser 2258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)from jinja2.nodes import EvalContext 23b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2.optimizer import optimize 24b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2.compiler import generate 25b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2.runtime import Undefined, new_context 26b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2.exceptions import TemplateSyntaxError, TemplateNotFound, \ 2758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) TemplatesNotFound, TemplateRuntimeError 28b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2.utils import import_string, LRUCache, Markup, missing, \ 2958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) concat, consume, internalcode 3058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)from jinja2._compat import imap, ifilter, string_types, iteritems, \ 3158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) text_type, reraise, implements_iterator, implements_to_string, \ 3258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) get_next, encode_filename, PY2, PYPY 3358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)from functools import reduce 34b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 35b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 36b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)# for direct template usage we have up to ten living environments 37b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)_spontaneous_environments = LRUCache(10) 38b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 39b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)# the function to create jinja traceback objects. This is dynamically 40b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)# imported on the first exception in the exception handler. 41b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)_make_traceback = None 42b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 43b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 44b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)def get_spontaneous_environment(*args): 45b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Return a new spontaneous environment. A spontaneous environment is an 46b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) unnamed and unaccessible (in theory) environment that is used for 47b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) templates generated from a string and not from the file system. 48b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 49b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 50b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) env = _spontaneous_environments.get(args) 51b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except TypeError: 52b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return Environment(*args) 53b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if env is not None: 54b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return env 55b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) _spontaneous_environments[args] = env = Environment(*args) 56b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) env.shared = True 57b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return env 58b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 59b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 60b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)def create_cache(size): 61b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Return the cache class for the given size.""" 62b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if size == 0: 63b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return None 64b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if size < 0: 65b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return {} 66b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return LRUCache(size) 67b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 68b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 69b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)def copy_cache(cache): 70b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Create an empty copy of the given cache.""" 71b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if cache is None: 72b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return None 73b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) elif type(cache) is dict: 74b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return {} 75b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return LRUCache(cache.capacity) 76b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 77b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 78b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)def load_extensions(environment, extensions): 79b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Load the extensions from the list and bind it to the environment. 8058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) Returns a dict of instantiated environments. 81b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 82b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) result = {} 83b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for extension in extensions: 8458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if isinstance(extension, string_types): 85b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) extension = import_string(extension) 86b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) result[extension.identifier] = extension(environment) 87b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return result 88b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 89b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 90b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)def _environment_sanity_check(environment): 91b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Perform a sanity check on the environment.""" 92b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) assert issubclass(environment.undefined, Undefined), 'undefined must ' \ 93b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 'be a subclass of undefined because filters depend on it.' 94b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) assert environment.block_start_string != \ 95b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) environment.variable_start_string != \ 96b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) environment.comment_start_string, 'block, variable and comment ' \ 97b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 'start strings must be different' 98b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) assert environment.newline_sequence in ('\r', '\r\n', '\n'), \ 99b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 'newline_sequence set to unknown line ending string.' 100b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return environment 101b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 102b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 103b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)class Environment(object): 104b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) r"""The core component of Jinja is the `Environment`. It contains 105b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) important shared variables like configuration, filters, tests, 106b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) globals and others. Instances of this class may be modified if 107b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) they are not shared and if no template was loaded so far. 108b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Modifications on environments after the first template was loaded 109b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) will lead to surprising effects and undefined behavior. 110b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 111b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Here the possible initialization parameters: 112b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 113b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `block_start_string` 114b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The string marking the begin of a block. Defaults to ``'{%'``. 115b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 116b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `block_end_string` 117b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The string marking the end of a block. Defaults to ``'%}'``. 118b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 119b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `variable_start_string` 120b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The string marking the begin of a print statement. 121b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Defaults to ``'{{'``. 122b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 123b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `variable_end_string` 124b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The string marking the end of a print statement. Defaults to 125b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ``'}}'``. 126b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 127b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `comment_start_string` 128b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The string marking the begin of a comment. Defaults to ``'{#'``. 129b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 130b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `comment_end_string` 131b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The string marking the end of a comment. Defaults to ``'#}'``. 132b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 133b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `line_statement_prefix` 134b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If given and a string, this will be used as prefix for line based 135b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) statements. See also :ref:`line-statements`. 136b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 137b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `line_comment_prefix` 138b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If given and a string, this will be used as prefix for line based 139b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) based comments. See also :ref:`line-statements`. 140b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 141b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.2 142b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 143b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `trim_blocks` 144b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If this is set to ``True`` the first newline after a block is 145b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) removed (block, not variable tag!). Defaults to `False`. 146b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 14758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) `lstrip_blocks` 14858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) If this is set to ``True`` leading spaces and tabs are stripped 14958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) from the start of a line to a block. Defaults to `False`. 15058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 151b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `newline_sequence` 152b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The sequence that starts a newline. Must be one of ``'\r'``, 153b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ``'\n'`` or ``'\r\n'``. The default is ``'\n'`` which is a 154b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) useful default for Linux and OS X systems as well as web 155b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) applications. 156b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 15758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) `keep_trailing_newline` 15858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) Preserve the trailing newline when rendering templates. 15958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) The default is ``False``, which causes a single newline, 16058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if present, to be stripped from the end of the template. 16158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 16258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) .. versionadded:: 2.7 16358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 164b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `extensions` 165b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) List of Jinja extensions to use. This can either be import paths 166b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) as strings or extension classes. For more information have a 167b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) look at :ref:`the extensions documentation <jinja-extensions>`. 168b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 169b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `optimized` 170b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) should the optimizer be enabled? Default is `True`. 171b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 172b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `undefined` 173b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :class:`Undefined` or a subclass of it that is used to represent 174b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) undefined values in the template. 175b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 176b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `finalize` 177b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) A callable that can be used to process the result of a variable 178b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) expression before it is output. For example one can convert 179b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `None` implicitly into an empty string here. 180b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 181b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `autoescape` 182b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If set to true the XML/HTML autoescaping feature is enabled by 183b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) default. For more details about auto escaping see 184b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :class:`~jinja2.utils.Markup`. As of Jinja 2.4 this can also 185b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) be a callable that is passed the template name and has to 186b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return `True` or `False` depending on autoescape should be 187b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) enabled by default. 188b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 189b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionchanged:: 2.4 190b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `autoescape` can now be a function 191b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 192b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `loader` 193b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The template loader for this environment. 194b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 195b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `cache_size` 196b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The size of the cache. Per default this is ``50`` which means 197b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) that if more than 50 templates are loaded the loader will clean 198b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) out the least recently used template. If the cache size is set to 199b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ``0`` templates are recompiled all the time, if the cache size is 200b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ``-1`` the cache will not be cleaned. 201b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 202b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `auto_reload` 203b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Some loaders load templates from locations where the template 204b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) sources may change (ie: file system or database). If 205b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `auto_reload` is set to `True` (default) every time a template is 206b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) requested the loader checks if the source changed and if yes, it 207b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) will reload the template. For higher performance it's possible to 208b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) disable that. 209b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 210b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `bytecode_cache` 211b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If set to a bytecode cache object, this object will provide a 212b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) cache for the internal Jinja bytecode so that templates don't 213b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) have to be parsed if they were not changed. 214b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 215b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) See :ref:`bytecode-cache` for more information. 216b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 217b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 218b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: if this environment is sandboxed. Modifying this variable won't make 219b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: the environment sandboxed though. For a real sandboxed environment 220b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: have a look at jinja2.sandbox. This flag alone controls the code 221b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: generation by the compiler. 222b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) sandboxed = False 223b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 224b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: True if the environment is just an overlay 225b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) overlayed = False 226b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 227b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: the environment this environment is linked to if it is an overlay 228b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) linked_to = None 229b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 230b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: shared environments have this set to `True`. A shared environment 231b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: must not be modified 232b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) shared = False 233b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 234b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) #: these are currently EXPERIMENTAL undocumented features. 235b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exception_handler = None 236b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exception_formatter = None 237b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 238b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __init__(self, 239b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) block_start_string=BLOCK_START_STRING, 240b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) block_end_string=BLOCK_END_STRING, 241b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) variable_start_string=VARIABLE_START_STRING, 242b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) variable_end_string=VARIABLE_END_STRING, 243b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) comment_start_string=COMMENT_START_STRING, 244b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) comment_end_string=COMMENT_END_STRING, 245b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) line_statement_prefix=LINE_STATEMENT_PREFIX, 246b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) line_comment_prefix=LINE_COMMENT_PREFIX, 247b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) trim_blocks=TRIM_BLOCKS, 24858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) lstrip_blocks=LSTRIP_BLOCKS, 249b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) newline_sequence=NEWLINE_SEQUENCE, 25058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) keep_trailing_newline=KEEP_TRAILING_NEWLINE, 251b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) extensions=(), 252b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) optimized=True, 253b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) undefined=Undefined, 254b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) finalize=None, 255b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) autoescape=False, 256b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) loader=None, 257b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) cache_size=50, 258b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) auto_reload=True, 259b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) bytecode_cache=None): 260b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # !!Important notice!! 261b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # The constructor accepts quite a few arguments that should be 262b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # passed by keyword rather than position. However it's important to 263b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # not change the order of arguments because it's used at least 264b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # internally in those cases: 26558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) # - spontaneous environments (i18n extension and Template) 266b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # - unittests 267b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # If parameter changes are required only add parameters at the end 268b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # and don't change the arguments (or the defaults!) of the arguments 269b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # existing already. 270b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 271b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # lexer / parser information 272b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.block_start_string = block_start_string 273b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.block_end_string = block_end_string 274b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.variable_start_string = variable_start_string 275b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.variable_end_string = variable_end_string 276b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.comment_start_string = comment_start_string 277b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.comment_end_string = comment_end_string 278b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.line_statement_prefix = line_statement_prefix 279b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.line_comment_prefix = line_comment_prefix 280b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.trim_blocks = trim_blocks 28158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) self.lstrip_blocks = lstrip_blocks 282b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.newline_sequence = newline_sequence 28358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) self.keep_trailing_newline = keep_trailing_newline 284b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 285b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # runtime information 286b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.undefined = undefined 287b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.optimized = optimized 288b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.finalize = finalize 289b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.autoescape = autoescape 290b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 291b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # defaults 292b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.filters = DEFAULT_FILTERS.copy() 293b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.tests = DEFAULT_TESTS.copy() 294b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.globals = DEFAULT_NAMESPACE.copy() 295b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 296b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # set the loader provided 297b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.loader = loader 298b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.cache = create_cache(cache_size) 299b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.bytecode_cache = bytecode_cache 300b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.auto_reload = auto_reload 301b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 302b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # load extensions 303b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.extensions = load_extensions(self, extensions) 304b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 305b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) _environment_sanity_check(self) 306b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 307b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def add_extension(self, extension): 308b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Adds an extension after the environment was created. 309b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 310b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.5 311b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 312b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.extensions.update(load_extensions(self, [extension])) 313b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 314b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def extend(self, **attributes): 315b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Add the items to the instance of the environment if they do not exist 316b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) yet. This is used by :ref:`extensions <writing-extensions>` to register 317b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) callbacks and configuration values without breaking inheritance. 318b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 31958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) for key, value in iteritems(attributes): 320b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not hasattr(self, key): 321b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) setattr(self, key, value) 322b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 323b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def overlay(self, block_start_string=missing, block_end_string=missing, 324b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) variable_start_string=missing, variable_end_string=missing, 325b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) comment_start_string=missing, comment_end_string=missing, 326b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) line_statement_prefix=missing, line_comment_prefix=missing, 32758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) trim_blocks=missing, lstrip_blocks=missing, 32858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) extensions=missing, optimized=missing, 329b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) undefined=missing, finalize=missing, autoescape=missing, 330b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) loader=missing, cache_size=missing, auto_reload=missing, 331b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) bytecode_cache=missing): 332b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Create a new overlay environment that shares all the data with the 333b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) current environment except of cache and the overridden attributes. 334b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Extensions cannot be removed for an overlayed environment. An overlayed 335b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) environment automatically gets all the extensions of the environment it 336b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) is linked to plus optional extra extensions. 337b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 338b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Creating overlays should happen after the initial environment was set 339b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) up completely. Not all attributes are truly linked, some are just 340b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) copied over so modifications on the original environment may not shine 341b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) through. 342b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 343b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) args = dict(locals()) 344b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) del args['self'], args['cache_size'], args['extensions'] 345b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 346b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv = object.__new__(self.__class__) 347b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv.__dict__.update(self.__dict__) 348b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv.overlayed = True 349b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv.linked_to = self 350b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 35158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) for key, value in iteritems(args): 352b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if value is not missing: 353b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) setattr(rv, key, value) 354b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 355b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if cache_size is not missing: 356b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv.cache = create_cache(cache_size) 357b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 358b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv.cache = copy_cache(self.cache) 359b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 360b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv.extensions = {} 36158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) for key, value in iteritems(self.extensions): 362b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv.extensions[key] = value.bind(rv) 363b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if extensions is not missing: 364b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv.extensions.update(load_extensions(rv, extensions)) 365b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 366b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return _environment_sanity_check(rv) 367b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 368b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) lexer = property(get_lexer, doc="The lexer for this environment.") 369b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 370b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def iter_extensions(self): 371b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Iterates over the extensions by priority.""" 372b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return iter(sorted(self.extensions.values(), 373b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) key=lambda x: x.priority)) 374b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 375b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def getitem(self, obj, argument): 376b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Get an item or attribute of an object but prefer the item.""" 377b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 378b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return obj[argument] 379b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except (TypeError, LookupError): 38058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if isinstance(argument, string_types): 381b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 382b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) attr = str(argument) 383b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except Exception: 384b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) pass 385b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 386b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 387b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return getattr(obj, attr) 388b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except AttributeError: 389b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) pass 390b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.undefined(obj=obj, name=argument) 391b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 392b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def getattr(self, obj, attribute): 393b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Get an item or attribute of an object but prefer the attribute. 394b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Unlike :meth:`getitem` the attribute *must* be a bytestring. 395b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 396b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 397b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return getattr(obj, attribute) 398b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except AttributeError: 399b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) pass 400b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 401b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return obj[attribute] 402b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except (TypeError, LookupError, AttributeError): 403b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.undefined(obj=obj, name=attribute) 404b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 40558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) def call_filter(self, name, value, args=None, kwargs=None, 40658537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) context=None, eval_ctx=None): 40758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) """Invokes a filter on a value the same way the compiler does it. 40858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 40958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) .. versionadded:: 2.7 41058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) """ 41158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) func = self.filters.get(name) 41258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if func is None: 41358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) raise TemplateRuntimeError('no filter named %r' % name) 41458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) args = [value] + list(args or ()) 41558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if getattr(func, 'contextfilter', False): 41658537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if context is None: 41758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) raise TemplateRuntimeError('Attempted to invoke context ' 41858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 'filter without context') 41958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) args.insert(0, context) 42058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) elif getattr(func, 'evalcontextfilter', False): 42158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if eval_ctx is None: 42258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if context is not None: 42358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) eval_ctx = context.eval_ctx 42458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) else: 42558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) eval_ctx = EvalContext(self) 42658537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) args.insert(0, eval_ctx) 42758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) elif getattr(func, 'environmentfilter', False): 42858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) args.insert(0, self) 42958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) return func(*args, **(kwargs or {})) 43058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 43158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) def call_test(self, name, value, args=None, kwargs=None): 43258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) """Invokes a test on a value the same way the compiler does it. 43358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 43458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) .. versionadded:: 2.7 43558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) """ 43658537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) func = self.tests.get(name) 43758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if func is None: 43858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) raise TemplateRuntimeError('no test named %r' % name) 43958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) return func(value, *(args or ()), **(kwargs or {})) 44058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 441b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @internalcode 442b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def parse(self, source, name=None, filename=None): 443b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Parse the sourcecode and return the abstract syntax tree. This 444b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) tree of nodes is used by the compiler to convert the template into 445b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) executable source- or bytecode. This is useful for debugging or to 446b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) extract information from templates. 447b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 448b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If you are :ref:`developing Jinja2 extensions <writing-extensions>` 449b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) this gives you a good overview of the node tree generated. 450b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 451b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 452b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self._parse(source, name, filename) 453b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except TemplateSyntaxError: 454b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_info = sys.exc_info() 455b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.handle_exception(exc_info, source_hint=source) 456b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 457b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def _parse(self, source, name, filename): 458b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Internal parsing function used by `parse` and `compile`.""" 45958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) return Parser(self, source, name, encode_filename(filename)).parse() 460b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 461b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def lex(self, source, name=None, filename=None): 462b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Lex the given sourcecode and return a generator that yields 463b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) tokens as tuples in the form ``(lineno, token_type, value)``. 464b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) This can be useful for :ref:`extension development <writing-extensions>` 465b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) and debugging templates. 466b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 467b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) This does not perform preprocessing. If you want the preprocessing 468b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) of the extensions to be applied you have to filter source through 469b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) the :meth:`preprocess` method. 470b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 47158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) source = text_type(source) 472b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 473b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.lexer.tokeniter(source, name, filename) 474b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except TemplateSyntaxError: 475b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_info = sys.exc_info() 476b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.handle_exception(exc_info, source_hint=source) 477b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 478b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def preprocess(self, source, name=None, filename=None): 479b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Preprocesses the source with all extensions. This is automatically 480b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) called for all parsing and compiling methods but *not* for :meth:`lex` 481b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) because there you usually only want the actual source tokenized. 482b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 483b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return reduce(lambda s, e: e.preprocess(s, name, filename), 48458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) self.iter_extensions(), text_type(source)) 485b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 486b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def _tokenize(self, source, name, filename=None, state=None): 487b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Called by the parser to do the preprocessing and filtering 488b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for all the extensions. Returns a :class:`~jinja2.lexer.TokenStream`. 489b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 490b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) source = self.preprocess(source, name, filename) 491b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) stream = self.lexer.tokenize(source, name, filename, state) 492b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for ext in self.iter_extensions(): 493b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) stream = ext.filter_stream(stream) 494b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not isinstance(stream, TokenStream): 495b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) stream = TokenStream(stream, name, filename) 496b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return stream 497b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 498b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def _generate(self, source, name, filename, defer_init=False): 49958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) """Internal hook that can be overridden to hook a different generate 500b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) method in. 501b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 502b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.5 503b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 504b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return generate(source, self, name, filename, defer_init=defer_init) 505b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 506b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def _compile(self, source, filename): 50758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) """Internal hook that can be overridden to hook a different compile 508b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) method in. 509b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 510b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.5 511b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 512b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return compile(source, filename, 'exec') 513b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 514b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @internalcode 515b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def compile(self, source, name=None, filename=None, raw=False, 516b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) defer_init=False): 517b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Compile a node or template source code. The `name` parameter is 518b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) the load name of the template after it was joined using 519b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :meth:`join_path` if necessary, not the filename on the file system. 520b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) the `filename` parameter is the estimated filename of the template on 521b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) the file system. If the template came from a database or memory this 522b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) can be omitted. 523b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 524b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The return value of this method is a python code object. If the `raw` 525b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) parameter is `True` the return value will be a string with python 526b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) code equivalent to the bytecode returned otherwise. This method is 527b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) mainly used internally. 528b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 529b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `defer_init` is use internally to aid the module code generator. This 530b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) causes the generated code to be able to import without the global 531b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) environment variable to be set. 532b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 533b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.4 534b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `defer_init` parameter added. 535b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 536b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) source_hint = None 537b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 53858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if isinstance(source, string_types): 539b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) source_hint = source 540b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) source = self._parse(source, name, filename) 541b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self.optimized: 542b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) source = optimize(source, self) 543b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) source = self._generate(source, name, filename, 544b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) defer_init=defer_init) 545b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if raw: 546b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return source 547b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if filename is None: 548b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) filename = '<template>' 549b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 55058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) filename = encode_filename(filename) 551b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self._compile(source, filename) 552b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except TemplateSyntaxError: 553b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_info = sys.exc_info() 554b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.handle_exception(exc_info, source_hint=source) 555b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 556b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def compile_expression(self, source, undefined_to_none=True): 557b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """A handy helper method that returns a callable that accepts keyword 558b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) arguments that appear as variables in the expression. If called it 559b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) returns the result of the expression. 560b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 561b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) This is useful if applications want to use the same rules as Jinja 562b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) in template "configuration files" or similar situations. 563b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 564b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Example usage: 565b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 566b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> env = Environment() 567b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> expr = env.compile_expression('foo == 42') 568b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> expr(foo=23) 569b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) False 570b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> expr(foo=42) 571b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) True 572b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 573b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Per default the return value is converted to `None` if the 574b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) expression returns an undefined value. This can be changed 575b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) by setting `undefined_to_none` to `False`. 576b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 577b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> env.compile_expression('var')() is None 578b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) True 579b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> env.compile_expression('var', undefined_to_none=False)() 580b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Undefined 581b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 582b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.1 583b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 584b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) parser = Parser(self, source, state='variable') 585b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_info = None 586b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 587b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) expr = parser.parse_expression() 588b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not parser.stream.eos: 589b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raise TemplateSyntaxError('chunk after expression', 590b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) parser.stream.current.lineno, 591b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) None, None) 592b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) expr.set_environment(self) 593b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except TemplateSyntaxError: 594b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_info = sys.exc_info() 595b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if exc_info is not None: 596b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.handle_exception(exc_info, source_hint=source) 597b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) body = [nodes.Assign(nodes.Name('result', 'store'), expr, lineno=1)] 598b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template = self.from_string(nodes.Template(body, lineno=1)) 599b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return TemplateExpression(template, undefined_to_none) 600b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 601b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def compile_templates(self, target, extensions=None, filter_func=None, 602b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) zip='deflated', log_function=None, 603b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ignore_errors=True, py_compile=False): 604b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Finds all the templates the loader can find, compiles them 605b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) and stores them in `target`. If `zip` is `None`, instead of in a 606b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) zipfile, the templates will be will be stored in a directory. 607b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) By default a deflate zip algorithm is used, to switch to 608b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) the stored algorithm, `zip` can be set to ``'stored'``. 609b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 610b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `extensions` and `filter_func` are passed to :meth:`list_templates`. 611b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Each template returned will be compiled to the target folder or 612b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) zipfile. 613b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 614b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) By default template compilation errors are ignored. In case a 615b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) log function is provided, errors are logged. If you want template 616b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) syntax errors to abort the compilation you can set `ignore_errors` 617b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) to `False` and you will get an exception on syntax errors. 618b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 619b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If `py_compile` is set to `True` .pyc files will be written to the 62058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) target instead of standard .py files. This flag does not do anything 62158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) on pypy and Python 3 where pyc files are not picked up by itself and 62258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) don't give much benefit. 623b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 624b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.4 625b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 626b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) from jinja2.loaders import ModuleLoader 627b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 628b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if log_function is None: 629b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) log_function = lambda x: None 630b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 631b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if py_compile: 63258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if not PY2 or PYPY: 63358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) from warnings import warn 63458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) warn(Warning('py_compile has no effect on pypy or Python 3')) 63558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) py_compile = False 63658537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) else: 63758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) import imp, marshal 63858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) py_header = imp.get_magic() + \ 63958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) u'\xff\xff\xff\xff'.encode('iso-8859-15') 64058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 64158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) # Python 3.3 added a source filesize to the header 64258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if sys.version_info >= (3, 3): 64358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) py_header += u'\x00\x00\x00\x00'.encode('iso-8859-15') 644b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 645b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def write_file(filename, data, mode): 646b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if zip: 647b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) info = ZipInfo(filename) 64858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) info.external_attr = 0o755 << 16 649b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) zip_file.writestr(info, data) 650b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 651b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) f = open(os.path.join(target, filename), mode) 652b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 653b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) f.write(data) 654b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) finally: 655b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) f.close() 656b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 657b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if zip is not None: 658b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) from zipfile import ZipFile, ZipInfo, ZIP_DEFLATED, ZIP_STORED 659b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) zip_file = ZipFile(target, 'w', dict(deflated=ZIP_DEFLATED, 660b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) stored=ZIP_STORED)[zip]) 661b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) log_function('Compiling into Zip archive "%s"' % target) 662b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 663b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not os.path.isdir(target): 664b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) os.makedirs(target) 665b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) log_function('Compiling into folder "%s"' % target) 666b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 667b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 668b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for name in self.list_templates(extensions, filter_func): 669b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) source, filename, _ = self.loader.get_source(self, name) 670b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 671b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) code = self.compile(source, name, filename, True, True) 67258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) except TemplateSyntaxError as e: 673b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not ignore_errors: 674b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raise 675b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) log_function('Could not compile "%s": %s' % (name, e)) 676b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) continue 677b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 678b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) filename = ModuleLoader.get_module_filename(name) 679b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 680b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if py_compile: 68158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) c = self._compile(code, encode_filename(filename)) 682b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) write_file(filename + 'c', py_header + 683b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) marshal.dumps(c), 'wb') 684b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) log_function('Byte-compiled "%s" as %s' % 685b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) (name, filename + 'c')) 686b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 687b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) write_file(filename, code, 'w') 688b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) log_function('Compiled "%s" as %s' % (name, filename)) 689b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) finally: 690b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if zip: 691b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) zip_file.close() 692b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 693b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) log_function('Finished compiling templates') 694b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 695b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def list_templates(self, extensions=None, filter_func=None): 696b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Returns a list of templates for this environment. This requires 697b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) that the loader supports the loader's 698b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :meth:`~BaseLoader.list_templates` method. 699b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 700b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If there are other files in the template folder besides the 701b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) actual templates, the returned list can be filtered. There are two 702b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ways: either `extensions` is set to a list of file extensions for 703b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) templates, or a `filter_func` can be provided which is a callable that 704b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) is passed a template name and should return `True` if it should end up 705b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) in the result list. 706b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 707b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If the loader does not support that, a :exc:`TypeError` is raised. 708b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 709b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.4 710b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 711b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) x = self.loader.list_templates() 712b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if extensions is not None: 713b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if filter_func is not None: 714b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raise TypeError('either extensions or filter_func ' 715b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 'can be passed, but not both') 716b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) filter_func = lambda x: '.' in x and \ 717b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) x.rsplit('.', 1)[1] in extensions 718b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if filter_func is not None: 71958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) x = ifilter(filter_func, x) 720b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return x 721b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 722b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def handle_exception(self, exc_info=None, rendered=False, source_hint=None): 723b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Exception handling helper. This is used internally to either raise 724b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rewritten exceptions or return a rendered traceback for the template. 725b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 726b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) global _make_traceback 727b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if exc_info is None: 728b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_info = sys.exc_info() 729b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 730b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # the debugging module is imported when it's used for the first time. 731b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # we're doing a lot of stuff there and for applications that do not 732b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # get any exceptions in template rendering there is no need to load 733b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # all of that. 734b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if _make_traceback is None: 735b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) from jinja2.debug import make_traceback as _make_traceback 736b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) traceback = _make_traceback(exc_info, source_hint) 737b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if rendered and self.exception_formatter is not None: 738b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.exception_formatter(traceback) 739b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self.exception_handler is not None: 740b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.exception_handler(traceback) 741b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_type, exc_value, tb = traceback.standard_exc_info 74258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) reraise(exc_type, exc_value, tb) 743b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 744b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def join_path(self, template, parent): 745b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Join a template with the parent. By default all the lookups are 746b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) relative to the loader root so this method returns the `template` 747b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) parameter unchanged, but if the paths should be relative to the 748b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) parent template, this function can be used to calculate the real 749b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template name. 750b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 751b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Subclasses may override this method and implement template path 752b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) joining here. 753b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 754b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return template 755b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 756b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @internalcode 757b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def _load_template(self, name, globals): 758b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self.loader is None: 759b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raise TypeError('no loader for this environment specified') 760b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self.cache is not None: 761b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template = self.cache.get(name) 762b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if template is not None and (not self.auto_reload or \ 763b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template.is_up_to_date): 764b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return template 765b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template = self.loader.load(self, name, globals) 766b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self.cache is not None: 767b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.cache[name] = template 768b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return template 769b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 770b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @internalcode 771b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def get_template(self, name, parent=None, globals=None): 772b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Load a template from the loader. If a loader is configured this 773b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) method ask the loader for the template and returns a :class:`Template`. 774b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If the `parent` parameter is not `None`, :meth:`join_path` is called 775b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) to get the real template name before loading. 776b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 777b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The `globals` parameter can be used to provide template wide globals. 778b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) These variables are available in the context at render time. 779b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 780b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If the template does not exist a :exc:`TemplateNotFound` exception is 781b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raised. 782b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 783b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionchanged:: 2.4 784b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If `name` is a :class:`Template` object it is returned from the 785b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) function unchanged. 786b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 787b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if isinstance(name, Template): 788b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return name 789b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if parent is not None: 790b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) name = self.join_path(name, parent) 791b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self._load_template(name, self.make_globals(globals)) 792b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 793b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @internalcode 794b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def select_template(self, names, parent=None, globals=None): 795b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Works like :meth:`get_template` but tries a number of templates 796b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) before it fails. If it cannot find any of the templates, it will 797b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raise a :exc:`TemplatesNotFound` exception. 798b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 799b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.3 800b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 801b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionchanged:: 2.4 802b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If `names` contains a :class:`Template` object it is returned 803b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) from the function unchanged. 804b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 805b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not names: 806b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raise TemplatesNotFound(message=u'Tried to select from an empty list ' 807b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) u'of templates.') 808b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) globals = self.make_globals(globals) 809b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for name in names: 810b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if isinstance(name, Template): 811b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return name 812b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if parent is not None: 813b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) name = self.join_path(name, parent) 814b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 815b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self._load_template(name, globals) 816b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except TemplateNotFound: 817b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) pass 818b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raise TemplatesNotFound(names) 819b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 820b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @internalcode 821b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def get_or_select_template(self, template_name_or_list, 822b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) parent=None, globals=None): 823b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Does a typecheck and dispatches to :meth:`select_template` 824b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if an iterable of template names is given, otherwise to 825b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :meth:`get_template`. 826b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 827b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.3 828b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 82958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if isinstance(template_name_or_list, string_types): 830b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.get_template(template_name_or_list, parent, globals) 831b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) elif isinstance(template_name_or_list, Template): 832b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return template_name_or_list 833b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.select_template(template_name_or_list, parent, globals) 834b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 835b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def from_string(self, source, globals=None, template_class=None): 836b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Load a template from a string. This parses the source given and 837b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) returns a :class:`Template` object. 838b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 839b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) globals = self.make_globals(globals) 840b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) cls = template_class or self.template_class 841b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return cls.from_code(self, self.compile(source), globals, None) 842b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 843b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def make_globals(self, d): 844b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Return a dict for the globals.""" 845b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not d: 846b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.globals 847b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return dict(self.globals, **d) 848b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 849b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 850b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)class Template(object): 851b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """The central template object. This class represents a compiled template 852b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) and is used to evaluate it. 853b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 854b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Normally the template object is generated from an :class:`Environment` but 855b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) it also has a constructor that makes it possible to create a template 856b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) instance directly using the constructor. It takes the same arguments as 857b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) the environment constructor but it's not possible to specify a loader. 858b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 859b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Every template object has a few methods and members that are guaranteed 860b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) to exist. However it's important that a template object should be 861b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) considered immutable. Modifications on the object are not supported. 862b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 863b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Template objects created from the constructor rather than an environment 864b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) do have an `environment` attribute that points to a temporary environment 865b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) that is probably shared with other templates created with the constructor 866b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) and compatible settings. 867b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 868b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> template = Template('Hello {{ name }}!') 869b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> template.render(name='John Doe') 870b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) u'Hello John Doe!' 871b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 872b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> stream = template.stream(name='John Doe') 873b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> stream.next() 874b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) u'Hello John Doe!' 875b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> stream.next() 876b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Traceback (most recent call last): 877b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ... 878b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) StopIteration 879b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 880b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 881b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __new__(cls, source, 882b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) block_start_string=BLOCK_START_STRING, 883b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) block_end_string=BLOCK_END_STRING, 884b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) variable_start_string=VARIABLE_START_STRING, 885b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) variable_end_string=VARIABLE_END_STRING, 886b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) comment_start_string=COMMENT_START_STRING, 887b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) comment_end_string=COMMENT_END_STRING, 888b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) line_statement_prefix=LINE_STATEMENT_PREFIX, 889b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) line_comment_prefix=LINE_COMMENT_PREFIX, 890b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) trim_blocks=TRIM_BLOCKS, 89158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) lstrip_blocks=LSTRIP_BLOCKS, 892b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) newline_sequence=NEWLINE_SEQUENCE, 89358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) keep_trailing_newline=KEEP_TRAILING_NEWLINE, 894b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) extensions=(), 895b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) optimized=True, 896b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) undefined=Undefined, 897b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) finalize=None, 898b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) autoescape=False): 899b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) env = get_spontaneous_environment( 900b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) block_start_string, block_end_string, variable_start_string, 901b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) variable_end_string, comment_start_string, comment_end_string, 902b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) line_statement_prefix, line_comment_prefix, trim_blocks, 90358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) lstrip_blocks, newline_sequence, keep_trailing_newline, 90458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) frozenset(extensions), optimized, undefined, finalize, autoescape, 90558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) None, 0, False, None) 906b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return env.from_string(source, template_class=cls) 907b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 908b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @classmethod 909b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def from_code(cls, environment, code, globals, uptodate=None): 910b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Creates a template object from compiled code and the globals. This 911b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) is used by the loaders and environment to create a template object. 912b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 913b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) namespace = { 914b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 'environment': environment, 915b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) '__file__': code.co_filename 916b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) } 91758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) exec(code, namespace) 918b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv = cls._from_namespace(environment, namespace, globals) 919b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv._uptodate = uptodate 920b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return rv 921b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 922b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @classmethod 923b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def from_module_dict(cls, environment, module_dict, globals): 924b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Creates a template object from a module. This is used by the 925b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) module loader to create a template object. 926b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 927b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) .. versionadded:: 2.4 928b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 929b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return cls._from_namespace(environment, module_dict, globals) 930b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 931b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @classmethod 932b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def _from_namespace(cls, environment, namespace, globals): 933b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t = object.__new__(cls) 934b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t.environment = environment 935b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t.globals = globals 936b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t.name = namespace['name'] 937b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t.filename = namespace['__file__'] 938b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t.blocks = namespace['blocks'] 939b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 940b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # render function and module 941b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t.root_render_func = namespace['root'] 942b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t._module = None 943b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 944b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # debug and loader helpers 945b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t._debug_info = namespace['debug_info'] 946b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) t._uptodate = None 947b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 948b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) # store the reference 949b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) namespace['environment'] = environment 950b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) namespace['__jinja_template__'] = t 951b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 952b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return t 953b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 954b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def render(self, *args, **kwargs): 955b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """This method accepts the same arguments as the `dict` constructor: 956b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) A dict, a dict subclass or some keyword arguments. If no arguments 957b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) are given the context will be empty. These two calls do the same:: 958b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 959b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template.render(knights='that say nih') 960b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template.render({'knights': 'that say nih'}) 961b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 962b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) This will return the rendered template as unicode string. 963b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 964b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) vars = dict(*args, **kwargs) 965b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 966b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return concat(self.root_render_func(self.new_context(vars))) 967b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except Exception: 968b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_info = sys.exc_info() 969b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.environment.handle_exception(exc_info, True) 970b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 971b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def stream(self, *args, **kwargs): 972b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Works exactly like :meth:`generate` but returns a 973b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :class:`TemplateStream`. 974b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 975b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return TemplateStream(self.generate(*args, **kwargs)) 976b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 977b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def generate(self, *args, **kwargs): 978b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """For very large templates it can be useful to not render the whole 979b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template at once but evaluate each statement after another and yield 980b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) piece for piece. This method basically does exactly that and returns 981b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) a generator that yields one item after another as unicode strings. 982b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 983b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) It accepts the same arguments as :meth:`render`. 984b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 985b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) vars = dict(*args, **kwargs) 986b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 987b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for event in self.root_render_func(self.new_context(vars)): 988b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) yield event 989b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except Exception: 990b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exc_info = sys.exc_info() 991b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 992b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return 993b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) yield self.environment.handle_exception(exc_info, True) 994b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 995b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def new_context(self, vars=None, shared=False, locals=None): 996b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Create a new :class:`Context` for this template. The vars 997b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) provided will be passed to the template. Per default the globals 998b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) are added to the context. If shared is set to `True` the data 999b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) is passed as it to the context without adding the globals. 1000b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1001b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) `locals` can be a dict of local variables for internal usage. 1002b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 1003b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return new_context(self.environment, self.name, self.blocks, 1004b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) vars, shared, self.globals, locals) 1005b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1006b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def make_module(self, vars=None, shared=False, locals=None): 1007b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """This method works like the :attr:`module` attribute when called 1008b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) without arguments but it will evaluate the template on every call 1009b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rather than caching it. It's also possible to provide 1010b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) a dict which is then used as context. The arguments are the same 1011b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) as for the :meth:`new_context` method. 1012b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 1013b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return TemplateModule(self, self.new_context(vars, shared, locals)) 1014b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1015b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @property 1016b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def module(self): 1017b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """The template as module. This is used for imports in the 1018b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template runtime but is also useful if one wants to access 1019b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exported template variables from the Python layer: 1020b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1021b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> t = Template('{% macro foo() %}42{% endmacro %}23') 1022b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> unicode(t.module) 1023b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) u'23' 1024b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) >>> t.module.foo() 1025b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) u'42' 1026b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 1027b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self._module is not None: 1028b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self._module 1029b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self._module = rv = self.make_module() 1030b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return rv 1031b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1032b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def get_corresponding_lineno(self, lineno): 1033b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Return the source line number of a line number in the 1034b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) generated bytecode as they are not in sync. 1035b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 1036b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for template_line, code_line in reversed(self.debug_info): 1037b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if code_line <= lineno: 1038b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return template_line 1039b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return 1 1040b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1041b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @property 1042b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def is_up_to_date(self): 1043b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """If this variable is `False` there is a newer version available.""" 1044b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self._uptodate is None: 1045b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return True 1046b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self._uptodate() 1047b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1048b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) @property 1049b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def debug_info(self): 1050b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """The debug info mapping.""" 105158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) return [tuple(imap(int, x.split('='))) for x in 1052b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self._debug_info.split('&')] 1053b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1054b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __repr__(self): 1055b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self.name is None: 1056b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) name = 'memory:%x' % id(self) 1057b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 1058b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) name = repr(self.name) 1059b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return '<%s %s>' % (self.__class__.__name__, name) 1060b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1061b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 106258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)@implements_to_string 1063b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)class TemplateModule(object): 1064b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Represents an imported template. All the exported names of the 1065b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) template are available as attributes on this object. Additionally 1066b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) converting it into an unicode- or bytestrings renders the contents. 1067b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 1068b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1069b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __init__(self, template, context): 1070b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self._body_stream = list(template.root_render_func(context)) 1071b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.__dict__.update(context.get_exported()) 1072b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.__name__ = template.name 1073b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1074b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __html__(self): 1075b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return Markup(concat(self._body_stream)) 1076b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1077b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __str__(self): 1078b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return concat(self._body_stream) 1079b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1080b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __repr__(self): 1081b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self.__name__ is None: 1082b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) name = 'memory:%x' % id(self) 1083b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 1084b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) name = repr(self.__name__) 1085b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return '<%s %s>' % (self.__class__.__name__, name) 1086b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1087b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1088b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)class TemplateExpression(object): 1089b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """The :meth:`jinja2.Environment.compile_expression` method returns an 1090b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) instance of this object. It encapsulates the expression-like access 1091b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) to the template with an expression it wraps. 1092b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 1093b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1094b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __init__(self, template, undefined_to_none): 1095b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self._template = template 1096b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self._undefined_to_none = undefined_to_none 1097b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1098b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __call__(self, *args, **kwargs): 1099b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) context = self._template.new_context(dict(*args, **kwargs)) 1100b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) consume(self._template.root_render_func(context)) 1101b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv = context.vars['result'] 1102b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if self._undefined_to_none and isinstance(rv, Undefined): 1103b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv = None 1104b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return rv 1105b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1106b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 110758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)@implements_iterator 1108b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)class TemplateStream(object): 1109b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """A template stream works pretty much like an ordinary python generator 1110b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) but it can buffer multiple items to reduce the number of total iterations. 1111b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Per default the output is unbuffered which means that for every unbuffered 1112b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) instruction in the template one unicode string is yielded. 1113b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1114b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) If buffering is enabled with a buffer size of 5, five items are combined 1115b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) into a new unicode string. This is mainly useful if you are streaming 1116b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) big templates to a client via WSGI which flushes after each iteration. 1117b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 1118b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1119b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __init__(self, gen): 1120b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self._gen = gen 1121b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.disable_buffering() 1122b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1123b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def dump(self, fp, encoding=None, errors='strict'): 1124b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Dump the complete stream into a file or file-like object. 1125b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Per default unicode strings are written, if you want to encode 112658537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) before writing specify an `encoding`. 1127b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1128b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Example usage:: 1129b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1130b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Template('Hello {{ name }}!').stream(name='foo').dump('hello.html') 1131b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 1132b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) close = False 113358537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) if isinstance(fp, string_types): 113458537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) fp = open(fp, encoding is None and 'w' or 'wb') 1135b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) close = True 1136b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 1137b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if encoding is not None: 1138b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) iterable = (x.encode(encoding, errors) for x in self) 1139b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 1140b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) iterable = self 1141b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if hasattr(fp, 'writelines'): 1142b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) fp.writelines(iterable) 1143b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 1144b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for item in iterable: 1145b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) fp.write(item) 1146b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) finally: 1147b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if close: 1148b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) fp.close() 1149b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1150b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def disable_buffering(self): 1151b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Disable the output buffering.""" 115258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) self._next = get_next(self._gen) 1153b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.buffered = False 1154b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1155b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def enable_buffering(self, size=5): 1156b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Enable buffering. Buffer `size` items before yielding them.""" 1157b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if size <= 1: 1158b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) raise ValueError('buffer size too small') 1159b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1160b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def generator(next): 1161b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) buf = [] 1162b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) c_size = 0 1163b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) push = buf.append 1164b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1165b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) while 1: 1166b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) try: 1167b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) while c_size < size: 1168b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) c = next() 1169b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) push(c) 1170b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if c: 1171b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) c_size += 1 1172b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) except StopIteration: 1173b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not c_size: 1174b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return 1175b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) yield concat(buf) 1176b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) del buf[:] 1177b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) c_size = 0 1178b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1179b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.buffered = True 118058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) self._next = get_next(generator(get_next(self._gen))) 1181b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1182b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def __iter__(self): 1183b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self 1184b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 118558537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) def __next__(self): 1186b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self._next() 1187b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1188b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 1189b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)# hook in default template class. if anyone reads this comment: ignore that 1190b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)# it's possible to use custom templates ;-) 1191b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)Environment.template_class = Template 1192