1645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez# -*- coding: utf-8 -*- 2645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez""" 3645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez jinja2.environment 4645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez ~~~~~~~~~~~~~~~~~~ 5645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 6645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Provides a class that holds runtime and parsing time options. 7645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 8645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez :copyright: (c) 2010 by the Jinja Team. 9645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez :license: BSD, see LICENSE for more details. 10645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez""" 11645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezimport os 12645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezimport sys 13645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2 import nodes 14645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.defaults import BLOCK_START_STRING, \ 15645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez BLOCK_END_STRING, VARIABLE_START_STRING, VARIABLE_END_STRING, \ 16645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez COMMENT_START_STRING, COMMENT_END_STRING, LINE_STATEMENT_PREFIX, \ 17645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez LINE_COMMENT_PREFIX, TRIM_BLOCKS, NEWLINE_SEQUENCE, \ 18645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez DEFAULT_FILTERS, DEFAULT_TESTS, DEFAULT_NAMESPACE, \ 19645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez KEEP_TRAILING_NEWLINE, LSTRIP_BLOCKS 20645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.lexer import get_lexer, TokenStream 21645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.parser import Parser 22645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.nodes import EvalContext 23645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.optimizer import optimize 24645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.compiler import generate 25645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.runtime import Undefined, new_context 26645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.exceptions import TemplateSyntaxError, TemplateNotFound, \ 27645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez TemplatesNotFound, TemplateRuntimeError 28645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2.utils import import_string, LRUCache, Markup, missing, \ 29645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez concat, consume, internalcode 30645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom jinja2._compat import imap, ifilter, string_types, iteritems, \ 31645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez text_type, reraise, implements_iterator, implements_to_string, \ 32645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez get_next, encode_filename, PY2, PYPY 33645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezfrom functools import reduce 34645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 35645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 36645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez# for direct template usage we have up to ten living environments 37645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez_spontaneous_environments = LRUCache(10) 38645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 39645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez# the function to create jinja traceback objects. This is dynamically 40645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez# imported on the first exception in the exception handler. 41645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez_make_traceback = None 42645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 43645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 44645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezdef get_spontaneous_environment(*args): 45645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Return a new spontaneous environment. A spontaneous environment is an 46645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez unnamed and unaccessible (in theory) environment that is used for 47645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez templates generated from a string and not from the file system. 48645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 49645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 50645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez env = _spontaneous_environments.get(args) 51645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except TypeError: 52645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return Environment(*args) 53645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if env is not None: 54645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return env 55645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez _spontaneous_environments[args] = env = Environment(*args) 56645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez env.shared = True 57645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return env 58645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 59645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 60645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezdef create_cache(size): 61645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Return the cache class for the given size.""" 62645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if size == 0: 63645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return None 64645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if size < 0: 65645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return {} 66645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return LRUCache(size) 67645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 68645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 69645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezdef copy_cache(cache): 70645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Create an empty copy of the given cache.""" 71645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if cache is None: 72645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return None 73645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez elif type(cache) is dict: 74645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return {} 75645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return LRUCache(cache.capacity) 76645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 77645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 78645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezdef load_extensions(environment, extensions): 79645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Load the extensions from the list and bind it to the environment. 80645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Returns a dict of instantiated environments. 81645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 82645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez result = {} 83645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for extension in extensions: 84645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if isinstance(extension, string_types): 85645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez extension = import_string(extension) 86645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez result[extension.identifier] = extension(environment) 87645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return result 88645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 89645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 90645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezdef _environment_sanity_check(environment): 91645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Perform a sanity check on the environment.""" 92645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez assert issubclass(environment.undefined, Undefined), 'undefined must ' \ 93645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 'be a subclass of undefined because filters depend on it.' 94645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez assert environment.block_start_string != \ 95645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez environment.variable_start_string != \ 96645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez environment.comment_start_string, 'block, variable and comment ' \ 97645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 'start strings must be different' 98645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez assert environment.newline_sequence in ('\r', '\r\n', '\n'), \ 99645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 'newline_sequence set to unknown line ending string.' 100645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return environment 101645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 102645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 103645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezclass Environment(object): 104645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez r"""The core component of Jinja is the `Environment`. It contains 105645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez important shared variables like configuration, filters, tests, 106645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez globals and others. Instances of this class may be modified if 107645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez they are not shared and if no template was loaded so far. 108645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Modifications on environments after the first template was loaded 109645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez will lead to surprising effects and undefined behavior. 110645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 111645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Here the possible initialization parameters: 112645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 113645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `block_start_string` 114645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The string marking the begin of a block. Defaults to ``'{%'``. 115645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 116645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `block_end_string` 117645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The string marking the end of a block. Defaults to ``'%}'``. 118645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 119645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `variable_start_string` 120645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The string marking the begin of a print statement. 121645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Defaults to ``'{{'``. 122645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 123645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `variable_end_string` 124645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The string marking the end of a print statement. Defaults to 125645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez ``'}}'``. 126645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 127645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `comment_start_string` 128645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The string marking the begin of a comment. Defaults to ``'{#'``. 129645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 130645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `comment_end_string` 131645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The string marking the end of a comment. Defaults to ``'#}'``. 132645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 133645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `line_statement_prefix` 134645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If given and a string, this will be used as prefix for line based 135645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez statements. See also :ref:`line-statements`. 136645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 137645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `line_comment_prefix` 138645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If given and a string, this will be used as prefix for line based 139645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez based comments. See also :ref:`line-statements`. 140645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 141645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.2 142645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 143645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `trim_blocks` 144645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If this is set to ``True`` the first newline after a block is 145645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez removed (block, not variable tag!). Defaults to `False`. 146645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 147645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `lstrip_blocks` 148645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If this is set to ``True`` leading spaces and tabs are stripped 149645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez from the start of a line to a block. Defaults to `False`. 150645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 151645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `newline_sequence` 152645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The sequence that starts a newline. Must be one of ``'\r'``, 153645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez ``'\n'`` or ``'\r\n'``. The default is ``'\n'`` which is a 154645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez useful default for Linux and OS X systems as well as web 155645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez applications. 156645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 157645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `keep_trailing_newline` 158645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Preserve the trailing newline when rendering templates. 159645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The default is ``False``, which causes a single newline, 160645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if present, to be stripped from the end of the template. 161645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 162645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.7 163645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 164645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `extensions` 165645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez List of Jinja extensions to use. This can either be import paths 166645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez as strings or extension classes. For more information have a 167645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez look at :ref:`the extensions documentation <jinja-extensions>`. 168645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 169645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `optimized` 170645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez should the optimizer be enabled? Default is `True`. 171645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 172645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `undefined` 173645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez :class:`Undefined` or a subclass of it that is used to represent 174645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez undefined values in the template. 175645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 176645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `finalize` 177645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez A callable that can be used to process the result of a variable 178645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez expression before it is output. For example one can convert 179645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `None` implicitly into an empty string here. 180645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 181645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `autoescape` 182645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If set to true the XML/HTML autoescaping feature is enabled by 183645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez default. For more details about auto escaping see 184645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez :class:`~jinja2.utils.Markup`. As of Jinja 2.4 this can also 185645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez be a callable that is passed the template name and has to 186645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return `True` or `False` depending on autoescape should be 187645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez enabled by default. 188645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 189645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionchanged:: 2.4 190645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `autoescape` can now be a function 191645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 192645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `loader` 193645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The template loader for this environment. 194645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 195645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `cache_size` 196645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The size of the cache. Per default this is ``50`` which means 197645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez that if more than 50 templates are loaded the loader will clean 198645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez out the least recently used template. If the cache size is set to 199645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez ``0`` templates are recompiled all the time, if the cache size is 200645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez ``-1`` the cache will not be cleaned. 201645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 202645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `auto_reload` 203645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Some loaders load templates from locations where the template 204645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez sources may change (ie: file system or database). If 205645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `auto_reload` is set to `True` (default) every time a template is 206645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez requested the loader checks if the source changed and if yes, it 207645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez will reload the template. For higher performance it's possible to 208645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez disable that. 209645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 210645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `bytecode_cache` 211645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If set to a bytecode cache object, this object will provide a 212645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez cache for the internal Jinja bytecode so that templates don't 213645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez have to be parsed if they were not changed. 214645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 215645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez See :ref:`bytecode-cache` for more information. 216645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 217645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 218645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: if this environment is sandboxed. Modifying this variable won't make 219645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: the environment sandboxed though. For a real sandboxed environment 220645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: have a look at jinja2.sandbox. This flag alone controls the code 221645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: generation by the compiler. 222645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez sandboxed = False 223645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 224645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: True if the environment is just an overlay 225645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez overlayed = False 226645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 227645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: the environment this environment is linked to if it is an overlay 228645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez linked_to = None 229645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 230645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: shared environments have this set to `True`. A shared environment 231645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: must not be modified 232645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez shared = False 233645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 234645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez #: these are currently EXPERIMENTAL undocumented features. 235645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exception_handler = None 236645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exception_formatter = None 237645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 238645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __init__(self, 239645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez block_start_string=BLOCK_START_STRING, 240645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez block_end_string=BLOCK_END_STRING, 241645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez variable_start_string=VARIABLE_START_STRING, 242645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez variable_end_string=VARIABLE_END_STRING, 243645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez comment_start_string=COMMENT_START_STRING, 244645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez comment_end_string=COMMENT_END_STRING, 245645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez line_statement_prefix=LINE_STATEMENT_PREFIX, 246645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez line_comment_prefix=LINE_COMMENT_PREFIX, 247645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez trim_blocks=TRIM_BLOCKS, 248645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez lstrip_blocks=LSTRIP_BLOCKS, 249645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez newline_sequence=NEWLINE_SEQUENCE, 250645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez keep_trailing_newline=KEEP_TRAILING_NEWLINE, 251645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez extensions=(), 252645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez optimized=True, 253645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez undefined=Undefined, 254645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez finalize=None, 255645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez autoescape=False, 256645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez loader=None, 257645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez cache_size=50, 258645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez auto_reload=True, 259645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez bytecode_cache=None): 260645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # !!Important notice!! 261645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # The constructor accepts quite a few arguments that should be 262645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # passed by keyword rather than position. However it's important to 263645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # not change the order of arguments because it's used at least 264645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # internally in those cases: 265645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # - spontaneous environments (i18n extension and Template) 266645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # - unittests 267645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # If parameter changes are required only add parameters at the end 268645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # and don't change the arguments (or the defaults!) of the arguments 269645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # existing already. 270645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 271645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # lexer / parser information 272645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.block_start_string = block_start_string 273645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.block_end_string = block_end_string 274645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.variable_start_string = variable_start_string 275645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.variable_end_string = variable_end_string 276645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.comment_start_string = comment_start_string 277645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.comment_end_string = comment_end_string 278645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.line_statement_prefix = line_statement_prefix 279645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.line_comment_prefix = line_comment_prefix 280645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.trim_blocks = trim_blocks 281645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.lstrip_blocks = lstrip_blocks 282645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.newline_sequence = newline_sequence 283645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.keep_trailing_newline = keep_trailing_newline 284645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 285645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # runtime information 286645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.undefined = undefined 287645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.optimized = optimized 288645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.finalize = finalize 289645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.autoescape = autoescape 290645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 291645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # defaults 292645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.filters = DEFAULT_FILTERS.copy() 293645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.tests = DEFAULT_TESTS.copy() 294645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.globals = DEFAULT_NAMESPACE.copy() 295645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 296645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # set the loader provided 297645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.loader = loader 298645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.cache = create_cache(cache_size) 299645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.bytecode_cache = bytecode_cache 300645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.auto_reload = auto_reload 301645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 302645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # load extensions 303645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.extensions = load_extensions(self, extensions) 304645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 305645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez _environment_sanity_check(self) 306645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 307645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def add_extension(self, extension): 308645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Adds an extension after the environment was created. 309645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 310645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.5 311645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 312645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.extensions.update(load_extensions(self, [extension])) 313645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 314645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def extend(self, **attributes): 315645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Add the items to the instance of the environment if they do not exist 316645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez yet. This is used by :ref:`extensions <writing-extensions>` to register 317645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez callbacks and configuration values without breaking inheritance. 318645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 319645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for key, value in iteritems(attributes): 320645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not hasattr(self, key): 321645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez setattr(self, key, value) 322645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 323645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def overlay(self, block_start_string=missing, block_end_string=missing, 324645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez variable_start_string=missing, variable_end_string=missing, 325645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez comment_start_string=missing, comment_end_string=missing, 326645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez line_statement_prefix=missing, line_comment_prefix=missing, 327645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez trim_blocks=missing, lstrip_blocks=missing, 328645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez extensions=missing, optimized=missing, 329645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez undefined=missing, finalize=missing, autoescape=missing, 330645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez loader=missing, cache_size=missing, auto_reload=missing, 331645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez bytecode_cache=missing): 332645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Create a new overlay environment that shares all the data with the 333645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez current environment except of cache and the overridden attributes. 334645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Extensions cannot be removed for an overlayed environment. An overlayed 335645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez environment automatically gets all the extensions of the environment it 336645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez is linked to plus optional extra extensions. 337645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 338645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Creating overlays should happen after the initial environment was set 339645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez up completely. Not all attributes are truly linked, some are just 340645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez copied over so modifications on the original environment may not shine 341645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez through. 342645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 343645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez args = dict(locals()) 344645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez del args['self'], args['cache_size'], args['extensions'] 345645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 346645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv = object.__new__(self.__class__) 347645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv.__dict__.update(self.__dict__) 348645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv.overlayed = True 349645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv.linked_to = self 350645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 351645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for key, value in iteritems(args): 352645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if value is not missing: 353645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez setattr(rv, key, value) 354645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 355645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if cache_size is not missing: 356645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv.cache = create_cache(cache_size) 357645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 358645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv.cache = copy_cache(self.cache) 359645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 360645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv.extensions = {} 361645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for key, value in iteritems(self.extensions): 362645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv.extensions[key] = value.bind(rv) 363645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if extensions is not missing: 364645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv.extensions.update(load_extensions(rv, extensions)) 365645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 366645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return _environment_sanity_check(rv) 367645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 368645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez lexer = property(get_lexer, doc="The lexer for this environment.") 369645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 370645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def iter_extensions(self): 371645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Iterates over the extensions by priority.""" 372645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return iter(sorted(self.extensions.values(), 373645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez key=lambda x: x.priority)) 374645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 375645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def getitem(self, obj, argument): 376645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Get an item or attribute of an object but prefer the item.""" 377645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 378645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return obj[argument] 379645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except (TypeError, LookupError): 380645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if isinstance(argument, string_types): 381645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 382645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez attr = str(argument) 383645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except Exception: 384645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez pass 385645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 386645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 387645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return getattr(obj, attr) 388645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except AttributeError: 389645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez pass 390645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self.undefined(obj=obj, name=argument) 391645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 392645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def getattr(self, obj, attribute): 393645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Get an item or attribute of an object but prefer the attribute. 394645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Unlike :meth:`getitem` the attribute *must* be a bytestring. 395645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 396645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 397645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return getattr(obj, attribute) 398645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except AttributeError: 399645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez pass 400645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 401645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return obj[attribute] 402645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except (TypeError, LookupError, AttributeError): 403645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self.undefined(obj=obj, name=attribute) 404645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 405645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def call_filter(self, name, value, args=None, kwargs=None, 406645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez context=None, eval_ctx=None): 407645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Invokes a filter on a value the same way the compiler does it. 408645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 409645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.7 410645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 411645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez func = self.filters.get(name) 412645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if func is None: 413645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise TemplateRuntimeError('no filter named %r' % name) 414645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez args = [value] + list(args or ()) 415645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if getattr(func, 'contextfilter', False): 416645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if context is None: 417645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise TemplateRuntimeError('Attempted to invoke context ' 418645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 'filter without context') 419645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez args.insert(0, context) 420645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez elif getattr(func, 'evalcontextfilter', False): 421645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if eval_ctx is None: 422645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if context is not None: 423645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez eval_ctx = context.eval_ctx 424645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 425645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez eval_ctx = EvalContext(self) 426645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez args.insert(0, eval_ctx) 427645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez elif getattr(func, 'environmentfilter', False): 428645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez args.insert(0, self) 429645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return func(*args, **(kwargs or {})) 430645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 431645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def call_test(self, name, value, args=None, kwargs=None): 432645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Invokes a test on a value the same way the compiler does it. 433645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 434645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.7 435645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 436645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez func = self.tests.get(name) 437645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if func is None: 438645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise TemplateRuntimeError('no test named %r' % name) 439645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return func(value, *(args or ()), **(kwargs or {})) 440645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 441645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @internalcode 442645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def parse(self, source, name=None, filename=None): 443645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Parse the sourcecode and return the abstract syntax tree. This 444645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez tree of nodes is used by the compiler to convert the template into 445645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez executable source- or bytecode. This is useful for debugging or to 446645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez extract information from templates. 447645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 448645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If you are :ref:`developing Jinja2 extensions <writing-extensions>` 449645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez this gives you a good overview of the node tree generated. 450645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 451645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 452645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self._parse(source, name, filename) 453645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except TemplateSyntaxError: 454645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_info = sys.exc_info() 455645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.handle_exception(exc_info, source_hint=source) 456645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 457645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def _parse(self, source, name, filename): 458645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Internal parsing function used by `parse` and `compile`.""" 459645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return Parser(self, source, name, encode_filename(filename)).parse() 460645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 461645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def lex(self, source, name=None, filename=None): 462645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Lex the given sourcecode and return a generator that yields 463645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez tokens as tuples in the form ``(lineno, token_type, value)``. 464645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez This can be useful for :ref:`extension development <writing-extensions>` 465645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez and debugging templates. 466645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 467645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez This does not perform preprocessing. If you want the preprocessing 468645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez of the extensions to be applied you have to filter source through 469645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez the :meth:`preprocess` method. 470645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 471645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez source = text_type(source) 472645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 473645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self.lexer.tokeniter(source, name, filename) 474645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except TemplateSyntaxError: 475645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_info = sys.exc_info() 476645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.handle_exception(exc_info, source_hint=source) 477645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 478645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def preprocess(self, source, name=None, filename=None): 479645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Preprocesses the source with all extensions. This is automatically 480645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez called for all parsing and compiling methods but *not* for :meth:`lex` 481645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez because there you usually only want the actual source tokenized. 482645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 483645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return reduce(lambda s, e: e.preprocess(s, name, filename), 484645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.iter_extensions(), text_type(source)) 485645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 486645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def _tokenize(self, source, name, filename=None, state=None): 487645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Called by the parser to do the preprocessing and filtering 488645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for all the extensions. Returns a :class:`~jinja2.lexer.TokenStream`. 489645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 490645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez source = self.preprocess(source, name, filename) 491645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez stream = self.lexer.tokenize(source, name, filename, state) 492645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for ext in self.iter_extensions(): 493645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez stream = ext.filter_stream(stream) 494645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not isinstance(stream, TokenStream): 495645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez stream = TokenStream(stream, name, filename) 496645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return stream 497645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 498645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def _generate(self, source, name, filename, defer_init=False): 499645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Internal hook that can be overridden to hook a different generate 500645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez method in. 501645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 502645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.5 503645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 504645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return generate(source, self, name, filename, defer_init=defer_init) 505645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 506645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def _compile(self, source, filename): 507645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Internal hook that can be overridden to hook a different compile 508645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez method in. 509645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 510645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.5 511645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 512645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return compile(source, filename, 'exec') 513645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 514645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @internalcode 515645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def compile(self, source, name=None, filename=None, raw=False, 516645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez defer_init=False): 517645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Compile a node or template source code. The `name` parameter is 518645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez the load name of the template after it was joined using 519645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez :meth:`join_path` if necessary, not the filename on the file system. 520645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez the `filename` parameter is the estimated filename of the template on 521645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez the file system. If the template came from a database or memory this 522645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez can be omitted. 523645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 524645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The return value of this method is a python code object. If the `raw` 525645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez parameter is `True` the return value will be a string with python 526645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez code equivalent to the bytecode returned otherwise. This method is 527645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez mainly used internally. 528645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 529645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `defer_init` is use internally to aid the module code generator. This 530645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez causes the generated code to be able to import without the global 531645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez environment variable to be set. 532645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 533645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.4 534645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `defer_init` parameter added. 535645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 536645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez source_hint = None 537645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 538645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if isinstance(source, string_types): 539645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez source_hint = source 540645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez source = self._parse(source, name, filename) 541645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self.optimized: 542645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez source = optimize(source, self) 543645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez source = self._generate(source, name, filename, 544645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez defer_init=defer_init) 545645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if raw: 546645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return source 547645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if filename is None: 548645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez filename = '<template>' 549645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 550645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez filename = encode_filename(filename) 551645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self._compile(source, filename) 552645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except TemplateSyntaxError: 553645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_info = sys.exc_info() 554645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.handle_exception(exc_info, source_hint=source) 555645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 556645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def compile_expression(self, source, undefined_to_none=True): 557645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """A handy helper method that returns a callable that accepts keyword 558645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez arguments that appear as variables in the expression. If called it 559645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez returns the result of the expression. 560645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 561645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez This is useful if applications want to use the same rules as Jinja 562645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez in template "configuration files" or similar situations. 563645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 564645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Example usage: 565645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 566645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> env = Environment() 567645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> expr = env.compile_expression('foo == 42') 568645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> expr(foo=23) 569645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez False 570645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> expr(foo=42) 571645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez True 572645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 573645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Per default the return value is converted to `None` if the 574645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez expression returns an undefined value. This can be changed 575645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez by setting `undefined_to_none` to `False`. 576645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 577645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> env.compile_expression('var')() is None 578645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez True 579645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> env.compile_expression('var', undefined_to_none=False)() 580645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Undefined 581645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 582645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.1 583645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 584645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez parser = Parser(self, source, state='variable') 585645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_info = None 586645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 587645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez expr = parser.parse_expression() 588645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not parser.stream.eos: 589645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise TemplateSyntaxError('chunk after expression', 590645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez parser.stream.current.lineno, 591645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez None, None) 592645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez expr.set_environment(self) 593645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except TemplateSyntaxError: 594645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_info = sys.exc_info() 595645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if exc_info is not None: 596645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.handle_exception(exc_info, source_hint=source) 597645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez body = [nodes.Assign(nodes.Name('result', 'store'), expr, lineno=1)] 598645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template = self.from_string(nodes.Template(body, lineno=1)) 599645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return TemplateExpression(template, undefined_to_none) 600645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 601645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def compile_templates(self, target, extensions=None, filter_func=None, 602645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez zip='deflated', log_function=None, 603645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez ignore_errors=True, py_compile=False): 604645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Finds all the templates the loader can find, compiles them 605645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez and stores them in `target`. If `zip` is `None`, instead of in a 606645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez zipfile, the templates will be will be stored in a directory. 607645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez By default a deflate zip algorithm is used, to switch to 608645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez the stored algorithm, `zip` can be set to ``'stored'``. 609645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 610645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `extensions` and `filter_func` are passed to :meth:`list_templates`. 611645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Each template returned will be compiled to the target folder or 612645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez zipfile. 613645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 614645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez By default template compilation errors are ignored. In case a 615645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez log function is provided, errors are logged. If you want template 616645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez syntax errors to abort the compilation you can set `ignore_errors` 617645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez to `False` and you will get an exception on syntax errors. 618645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 619645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If `py_compile` is set to `True` .pyc files will be written to the 620645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez target instead of standard .py files. This flag does not do anything 621645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez on pypy and Python 3 where pyc files are not picked up by itself and 622645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez don't give much benefit. 623645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 624645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.4 625645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 626645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez from jinja2.loaders import ModuleLoader 627645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 628645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if log_function is None: 629645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez log_function = lambda x: None 630645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 631645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if py_compile: 632645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not PY2 or PYPY: 633645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez from warnings import warn 634645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez warn(Warning('py_compile has no effect on pypy or Python 3')) 635645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez py_compile = False 636645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 637645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez import imp, marshal 638645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez py_header = imp.get_magic() + \ 639645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez u'\xff\xff\xff\xff'.encode('iso-8859-15') 640645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 641645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # Python 3.3 added a source filesize to the header 642645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if sys.version_info >= (3, 3): 643645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez py_header += u'\x00\x00\x00\x00'.encode('iso-8859-15') 644645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 645645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def write_file(filename, data, mode): 646645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if zip: 647645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez info = ZipInfo(filename) 648645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez info.external_attr = 0o755 << 16 649645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez zip_file.writestr(info, data) 650645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 651645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez f = open(os.path.join(target, filename), mode) 652645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 653645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez f.write(data) 654645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez finally: 655645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez f.close() 656645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 657645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if zip is not None: 658645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez from zipfile import ZipFile, ZipInfo, ZIP_DEFLATED, ZIP_STORED 659645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez zip_file = ZipFile(target, 'w', dict(deflated=ZIP_DEFLATED, 660645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez stored=ZIP_STORED)[zip]) 661645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez log_function('Compiling into Zip archive "%s"' % target) 662645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 663645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not os.path.isdir(target): 664645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez os.makedirs(target) 665645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez log_function('Compiling into folder "%s"' % target) 666645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 667645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 668645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for name in self.list_templates(extensions, filter_func): 669645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez source, filename, _ = self.loader.get_source(self, name) 670645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 671645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez code = self.compile(source, name, filename, True, True) 672645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except TemplateSyntaxError as e: 673645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not ignore_errors: 674645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise 675645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez log_function('Could not compile "%s": %s' % (name, e)) 676645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez continue 677645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 678645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez filename = ModuleLoader.get_module_filename(name) 679645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 680645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if py_compile: 681645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez c = self._compile(code, encode_filename(filename)) 682645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez write_file(filename + 'c', py_header + 683645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez marshal.dumps(c), 'wb') 684645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez log_function('Byte-compiled "%s" as %s' % 685645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez (name, filename + 'c')) 686645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 687645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez write_file(filename, code, 'w') 688645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez log_function('Compiled "%s" as %s' % (name, filename)) 689645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez finally: 690645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if zip: 691645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez zip_file.close() 692645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 693645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez log_function('Finished compiling templates') 694645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 695645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def list_templates(self, extensions=None, filter_func=None): 696645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Returns a list of templates for this environment. This requires 697645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez that the loader supports the loader's 698645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez :meth:`~BaseLoader.list_templates` method. 699645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 700645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If there are other files in the template folder besides the 701645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez actual templates, the returned list can be filtered. There are two 702645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez ways: either `extensions` is set to a list of file extensions for 703645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez templates, or a `filter_func` can be provided which is a callable that 704645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez is passed a template name and should return `True` if it should end up 705645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez in the result list. 706645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 707645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If the loader does not support that, a :exc:`TypeError` is raised. 708645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 709645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.4 710645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 711645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez x = self.loader.list_templates() 712645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if extensions is not None: 713645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if filter_func is not None: 714645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise TypeError('either extensions or filter_func ' 715645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 'can be passed, but not both') 716645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez filter_func = lambda x: '.' in x and \ 717645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez x.rsplit('.', 1)[1] in extensions 718645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if filter_func is not None: 719645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez x = ifilter(filter_func, x) 720645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return x 721645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 722645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def handle_exception(self, exc_info=None, rendered=False, source_hint=None): 723645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Exception handling helper. This is used internally to either raise 724645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rewritten exceptions or return a rendered traceback for the template. 725645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 726645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez global _make_traceback 727645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if exc_info is None: 728645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_info = sys.exc_info() 729645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 730645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # the debugging module is imported when it's used for the first time. 731645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # we're doing a lot of stuff there and for applications that do not 732645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # get any exceptions in template rendering there is no need to load 733645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # all of that. 734645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if _make_traceback is None: 735645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez from jinja2.debug import make_traceback as _make_traceback 736645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez traceback = _make_traceback(exc_info, source_hint) 737645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if rendered and self.exception_formatter is not None: 738645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self.exception_formatter(traceback) 739645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self.exception_handler is not None: 740645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.exception_handler(traceback) 741645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_type, exc_value, tb = traceback.standard_exc_info 742645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez reraise(exc_type, exc_value, tb) 743645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 744645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def join_path(self, template, parent): 745645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Join a template with the parent. By default all the lookups are 746645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez relative to the loader root so this method returns the `template` 747645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez parameter unchanged, but if the paths should be relative to the 748645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez parent template, this function can be used to calculate the real 749645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template name. 750645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 751645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Subclasses may override this method and implement template path 752645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez joining here. 753645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 754645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return template 755645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 756645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @internalcode 757645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def _load_template(self, name, globals): 758645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self.loader is None: 759645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise TypeError('no loader for this environment specified') 760645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self.cache is not None: 761645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template = self.cache.get(name) 762645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if template is not None and (not self.auto_reload or \ 763645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template.is_up_to_date): 764645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return template 765645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template = self.loader.load(self, name, globals) 766645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self.cache is not None: 767645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.cache[name] = template 768645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return template 769645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 770645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @internalcode 771645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def get_template(self, name, parent=None, globals=None): 772645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Load a template from the loader. If a loader is configured this 773645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez method ask the loader for the template and returns a :class:`Template`. 774645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If the `parent` parameter is not `None`, :meth:`join_path` is called 775645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez to get the real template name before loading. 776645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 777645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez The `globals` parameter can be used to provide template wide globals. 778645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez These variables are available in the context at render time. 779645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 780645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If the template does not exist a :exc:`TemplateNotFound` exception is 781645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raised. 782645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 783645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionchanged:: 2.4 784645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If `name` is a :class:`Template` object it is returned from the 785645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez function unchanged. 786645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 787645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if isinstance(name, Template): 788645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return name 789645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if parent is not None: 790645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez name = self.join_path(name, parent) 791645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self._load_template(name, self.make_globals(globals)) 792645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 793645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @internalcode 794645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def select_template(self, names, parent=None, globals=None): 795645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Works like :meth:`get_template` but tries a number of templates 796645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez before it fails. If it cannot find any of the templates, it will 797645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise a :exc:`TemplatesNotFound` exception. 798645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 799645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.3 800645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 801645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionchanged:: 2.4 802645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If `names` contains a :class:`Template` object it is returned 803645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez from the function unchanged. 804645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 805645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not names: 806645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise TemplatesNotFound(message=u'Tried to select from an empty list ' 807645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez u'of templates.') 808645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez globals = self.make_globals(globals) 809645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for name in names: 810645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if isinstance(name, Template): 811645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return name 812645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if parent is not None: 813645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez name = self.join_path(name, parent) 814645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 815645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self._load_template(name, globals) 816645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except TemplateNotFound: 817645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez pass 818645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise TemplatesNotFound(names) 819645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 820645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @internalcode 821645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def get_or_select_template(self, template_name_or_list, 822645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez parent=None, globals=None): 823645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Does a typecheck and dispatches to :meth:`select_template` 824645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if an iterable of template names is given, otherwise to 825645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez :meth:`get_template`. 826645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 827645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.3 828645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 829645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if isinstance(template_name_or_list, string_types): 830645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self.get_template(template_name_or_list, parent, globals) 831645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez elif isinstance(template_name_or_list, Template): 832645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return template_name_or_list 833645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self.select_template(template_name_or_list, parent, globals) 834645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 835645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def from_string(self, source, globals=None, template_class=None): 836645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Load a template from a string. This parses the source given and 837645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez returns a :class:`Template` object. 838645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 839645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez globals = self.make_globals(globals) 840645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez cls = template_class or self.template_class 841645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return cls.from_code(self, self.compile(source), globals, None) 842645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 843645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def make_globals(self, d): 844645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Return a dict for the globals.""" 845645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not d: 846645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self.globals 847645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return dict(self.globals, **d) 848645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 849645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 850645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezclass Template(object): 851645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """The central template object. This class represents a compiled template 852645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez and is used to evaluate it. 853645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 854645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Normally the template object is generated from an :class:`Environment` but 855645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez it also has a constructor that makes it possible to create a template 856645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez instance directly using the constructor. It takes the same arguments as 857645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez the environment constructor but it's not possible to specify a loader. 858645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 859645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Every template object has a few methods and members that are guaranteed 860645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez to exist. However it's important that a template object should be 861645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez considered immutable. Modifications on the object are not supported. 862645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 863645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Template objects created from the constructor rather than an environment 864645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez do have an `environment` attribute that points to a temporary environment 865645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez that is probably shared with other templates created with the constructor 866645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez and compatible settings. 867645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 868645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> template = Template('Hello {{ name }}!') 869645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> template.render(name='John Doe') 870645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez u'Hello John Doe!' 871645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 872645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> stream = template.stream(name='John Doe') 873645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> stream.next() 874645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez u'Hello John Doe!' 875645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> stream.next() 876645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Traceback (most recent call last): 877645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez ... 878645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez StopIteration 879645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 880645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 881645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __new__(cls, source, 882645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez block_start_string=BLOCK_START_STRING, 883645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez block_end_string=BLOCK_END_STRING, 884645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez variable_start_string=VARIABLE_START_STRING, 885645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez variable_end_string=VARIABLE_END_STRING, 886645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez comment_start_string=COMMENT_START_STRING, 887645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez comment_end_string=COMMENT_END_STRING, 888645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez line_statement_prefix=LINE_STATEMENT_PREFIX, 889645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez line_comment_prefix=LINE_COMMENT_PREFIX, 890645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez trim_blocks=TRIM_BLOCKS, 891645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez lstrip_blocks=LSTRIP_BLOCKS, 892645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez newline_sequence=NEWLINE_SEQUENCE, 893645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez keep_trailing_newline=KEEP_TRAILING_NEWLINE, 894645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez extensions=(), 895645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez optimized=True, 896645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez undefined=Undefined, 897645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez finalize=None, 898645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez autoescape=False): 899645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez env = get_spontaneous_environment( 900645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez block_start_string, block_end_string, variable_start_string, 901645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez variable_end_string, comment_start_string, comment_end_string, 902645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez line_statement_prefix, line_comment_prefix, trim_blocks, 903645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez lstrip_blocks, newline_sequence, keep_trailing_newline, 904645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez frozenset(extensions), optimized, undefined, finalize, autoescape, 905645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez None, 0, False, None) 906645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return env.from_string(source, template_class=cls) 907645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 908645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @classmethod 909645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def from_code(cls, environment, code, globals, uptodate=None): 910645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Creates a template object from compiled code and the globals. This 911645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez is used by the loaders and environment to create a template object. 912645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 913645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez namespace = { 914645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 'environment': environment, 915645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez '__file__': code.co_filename 916645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez } 917645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exec(code, namespace) 918645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv = cls._from_namespace(environment, namespace, globals) 919645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv._uptodate = uptodate 920645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return rv 921645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 922645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @classmethod 923645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def from_module_dict(cls, environment, module_dict, globals): 924645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Creates a template object from a module. This is used by the 925645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez module loader to create a template object. 926645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 927645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez .. versionadded:: 2.4 928645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 929645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return cls._from_namespace(environment, module_dict, globals) 930645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 931645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @classmethod 932645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def _from_namespace(cls, environment, namespace, globals): 933645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t = object.__new__(cls) 934645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t.environment = environment 935645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t.globals = globals 936645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t.name = namespace['name'] 937645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t.filename = namespace['__file__'] 938645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t.blocks = namespace['blocks'] 939645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 940645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # render function and module 941645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t.root_render_func = namespace['root'] 942645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t._module = None 943645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 944645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # debug and loader helpers 945645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t._debug_info = namespace['debug_info'] 946645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez t._uptodate = None 947645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 948645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez # store the reference 949645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez namespace['environment'] = environment 950645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez namespace['__jinja_template__'] = t 951645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 952645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return t 953645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 954645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def render(self, *args, **kwargs): 955645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """This method accepts the same arguments as the `dict` constructor: 956645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez A dict, a dict subclass or some keyword arguments. If no arguments 957645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez are given the context will be empty. These two calls do the same:: 958645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 959645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template.render(knights='that say nih') 960645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template.render({'knights': 'that say nih'}) 961645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 962645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez This will return the rendered template as unicode string. 963645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 964645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez vars = dict(*args, **kwargs) 965645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 966645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return concat(self.root_render_func(self.new_context(vars))) 967645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except Exception: 968645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_info = sys.exc_info() 969645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self.environment.handle_exception(exc_info, True) 970645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 971645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def stream(self, *args, **kwargs): 972645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Works exactly like :meth:`generate` but returns a 973645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez :class:`TemplateStream`. 974645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 975645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return TemplateStream(self.generate(*args, **kwargs)) 976645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 977645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def generate(self, *args, **kwargs): 978645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """For very large templates it can be useful to not render the whole 979645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template at once but evaluate each statement after another and yield 980645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez piece for piece. This method basically does exactly that and returns 981645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez a generator that yields one item after another as unicode strings. 982645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 983645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez It accepts the same arguments as :meth:`render`. 984645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 985645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez vars = dict(*args, **kwargs) 986645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 987645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for event in self.root_render_func(self.new_context(vars)): 988645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez yield event 989645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except Exception: 990645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exc_info = sys.exc_info() 991645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 992645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return 993645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez yield self.environment.handle_exception(exc_info, True) 994645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 995645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def new_context(self, vars=None, shared=False, locals=None): 996645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Create a new :class:`Context` for this template. The vars 997645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez provided will be passed to the template. Per default the globals 998645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez are added to the context. If shared is set to `True` the data 999645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez is passed as it to the context without adding the globals. 1000645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1001645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez `locals` can be a dict of local variables for internal usage. 1002645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 1003645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return new_context(self.environment, self.name, self.blocks, 1004645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez vars, shared, self.globals, locals) 1005645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1006645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def make_module(self, vars=None, shared=False, locals=None): 1007645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """This method works like the :attr:`module` attribute when called 1008645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez without arguments but it will evaluate the template on every call 1009645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rather than caching it. It's also possible to provide 1010645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez a dict which is then used as context. The arguments are the same 1011645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez as for the :meth:`new_context` method. 1012645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 1013645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return TemplateModule(self, self.new_context(vars, shared, locals)) 1014645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1015645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @property 1016645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def module(self): 1017645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """The template as module. This is used for imports in the 1018645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template runtime but is also useful if one wants to access 1019645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez exported template variables from the Python layer: 1020645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1021645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> t = Template('{% macro foo() %}42{% endmacro %}23') 1022645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> unicode(t.module) 1023645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez u'23' 1024645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez >>> t.module.foo() 1025645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez u'42' 1026645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 1027645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self._module is not None: 1028645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self._module 1029645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self._module = rv = self.make_module() 1030645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return rv 1031645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1032645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def get_corresponding_lineno(self, lineno): 1033645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Return the source line number of a line number in the 1034645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez generated bytecode as they are not in sync. 1035645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 1036645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for template_line, code_line in reversed(self.debug_info): 1037645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if code_line <= lineno: 1038645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return template_line 1039645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return 1 1040645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1041645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @property 1042645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def is_up_to_date(self): 1043645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """If this variable is `False` there is a newer version available.""" 1044645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self._uptodate is None: 1045645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return True 1046645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self._uptodate() 1047645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1048645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez @property 1049645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def debug_info(self): 1050645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """The debug info mapping.""" 1051645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return [tuple(imap(int, x.split('='))) for x in 1052645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self._debug_info.split('&')] 1053645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1054645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __repr__(self): 1055645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self.name is None: 1056645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez name = 'memory:%x' % id(self) 1057645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 1058645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez name = repr(self.name) 1059645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return '<%s %s>' % (self.__class__.__name__, name) 1060645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1061645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1062645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez@implements_to_string 1063645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezclass TemplateModule(object): 1064645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Represents an imported template. All the exported names of the 1065645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez template are available as attributes on this object. Additionally 1066645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez converting it into an unicode- or bytestrings renders the contents. 1067645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 1068645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1069645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __init__(self, template, context): 1070645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self._body_stream = list(template.root_render_func(context)) 1071645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.__dict__.update(context.get_exported()) 1072645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.__name__ = template.name 1073645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1074645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __html__(self): 1075645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return Markup(concat(self._body_stream)) 1076645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1077645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __str__(self): 1078645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return concat(self._body_stream) 1079645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1080645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __repr__(self): 1081645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self.__name__ is None: 1082645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez name = 'memory:%x' % id(self) 1083645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 1084645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez name = repr(self.__name__) 1085645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return '<%s %s>' % (self.__class__.__name__, name) 1086645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1087645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1088645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezclass TemplateExpression(object): 1089645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """The :meth:`jinja2.Environment.compile_expression` method returns an 1090645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez instance of this object. It encapsulates the expression-like access 1091645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez to the template with an expression it wraps. 1092645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 1093645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1094645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __init__(self, template, undefined_to_none): 1095645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self._template = template 1096645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self._undefined_to_none = undefined_to_none 1097645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1098645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __call__(self, *args, **kwargs): 1099645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez context = self._template.new_context(dict(*args, **kwargs)) 1100645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez consume(self._template.root_render_func(context)) 1101645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv = context.vars['result'] 1102645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if self._undefined_to_none and isinstance(rv, Undefined): 1103645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez rv = None 1104645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return rv 1105645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1106645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1107645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez@implements_iterator 1108645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavezclass TemplateStream(object): 1109645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """A template stream works pretty much like an ordinary python generator 1110645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez but it can buffer multiple items to reduce the number of total iterations. 1111645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Per default the output is unbuffered which means that for every unbuffered 1112645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez instruction in the template one unicode string is yielded. 1113645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1114645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez If buffering is enabled with a buffer size of 5, five items are combined 1115645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez into a new unicode string. This is mainly useful if you are streaming 1116645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez big templates to a client via WSGI which flushes after each iteration. 1117645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 1118645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1119645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __init__(self, gen): 1120645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self._gen = gen 1121645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.disable_buffering() 1122645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1123645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def dump(self, fp, encoding=None, errors='strict'): 1124645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Dump the complete stream into a file or file-like object. 1125645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Per default unicode strings are written, if you want to encode 1126645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez before writing specify an `encoding`. 1127645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1128645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Example usage:: 1129645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1130645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez Template('Hello {{ name }}!').stream(name='foo').dump('hello.html') 1131645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """ 1132645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez close = False 1133645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if isinstance(fp, string_types): 1134645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez fp = open(fp, encoding is None and 'w' or 'wb') 1135645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez close = True 1136645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 1137645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if encoding is not None: 1138645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez iterable = (x.encode(encoding, errors) for x in self) 1139645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 1140645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez iterable = self 1141645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if hasattr(fp, 'writelines'): 1142645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez fp.writelines(iterable) 1143645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez else: 1144645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez for item in iterable: 1145645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez fp.write(item) 1146645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez finally: 1147645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if close: 1148645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez fp.close() 1149645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1150645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def disable_buffering(self): 1151645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Disable the output buffering.""" 1152645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self._next = get_next(self._gen) 1153645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.buffered = False 1154645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1155645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def enable_buffering(self, size=5): 1156645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez """Enable buffering. Buffer `size` items before yielding them.""" 1157645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if size <= 1: 1158645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez raise ValueError('buffer size too small') 1159645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1160645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def generator(next): 1161645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez buf = [] 1162645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez c_size = 0 1163645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez push = buf.append 1164645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1165645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez while 1: 1166645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez try: 1167645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez while c_size < size: 1168645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez c = next() 1169645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez push(c) 1170645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if c: 1171645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez c_size += 1 1172645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez except StopIteration: 1173645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez if not c_size: 1174645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return 1175645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez yield concat(buf) 1176645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez del buf[:] 1177645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez c_size = 0 1178645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1179645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self.buffered = True 1180645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez self._next = get_next(generator(get_next(self._gen))) 1181645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1182645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __iter__(self): 1183645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self 1184645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1185645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez def __next__(self): 1186645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez return self._next() 1187645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1188645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez 1189645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez# hook in default template class. if anyone reads this comment: ignore that 1190645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector Chavez# it's possible to use custom templates ;-) 1191645501c2ab19a559ce82a1d5a29ced159a4c30fbLuis Hector ChavezEnvironment.template_class = Template 1192