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