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