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