jinja2/environment.py

   1 # -*- coding: utf-8 -*-
   2 """
   3     jinja2.environment
   4     ~~~~~~~~~~~~~~~~~~
   5
   6     Provides a class that holds runtime and parsing time options.
   7
   8     :copyright: 2008 by Armin Ronacher.
   9     :license: BSD, see LICENSE for more details.
  10 """
  11 import sys
  12 from jinja2.defaults import *
  13 from jinja2.lexer import Lexer
  14 from jinja2.parser import Parser
  15 from jinja2.optimizer import optimize
  16 from jinja2.compiler import generate
  17 from jinja2.runtime import Undefined, Context, concat
  18 from jinja2.debug import translate_exception, translate_syntax_error
  19 from jinja2.exceptions import TemplateSyntaxError
  20 from jinja2.utils import import_string, LRUCache, Markup, missing
  21
  22
  23 # for direct template usage we have up to ten living environments
  24 _spontaneous_environments = LRUCache(10)
  25
  26
  27 def get_spontaneous_environment(*args):
  28     """Return a new spontaneus environment.  A spontaneus environment is an
  29     unnamed and unaccessable (in theory) environment that is used for
  30     template generated from a string and not from the file system.
  31     """
  32     try:
  33         env = _spontaneous_environments.get(args)
  34     except TypeError:
  35         return Environment(*args)
  36     if env is not None:
  37         return env
  38     _spontaneous_environments[args] = env = Environment(*args)
  39     env.shared = True
  40     return env
  41
  42
  43 def create_cache(size):
  44     """Return the cache class for the given size."""
  45     if size == 0:
  46         return None
  47     if size < 0:
  48         return {}
  49     return LRUCache(size)
  50
  51
  52 def load_extensions(environment, extensions):
  53     """Load the extensions from the list and bind it to the environment.
  54     Returns a new list of instanciated environments.
  55     """
  56     result = []
  57     for extension in extensions:
  58         if isinstance(extension, basestring):
  59             extension = import_string(extension)
  60         result.append(extension(environment))
  61     return result
  62
  63
  64 def _environment_sanity_check(environment):
  65     """Perform a sanity check on the environment."""
  66     assert issubclass(environment.undefined, Undefined), 'undefined must ' \
  67            'be a subclass of undefined because filters depend on it.'
  68     assert environment.block_start_string != \
  69            environment.variable_start_string != \
  70            environment.comment_start_string, 'block, variable and comment ' \
  71            'start strings must be different'
  72     return environment
  73
  74
  75 class Environment(object):
  76     """The core component of Jinja is the `Environment`.  It contains
  77     important shared variables like configuration, filters, tests,
  78     globals and others.  Instances of this class may be modified if
  79     they are not shared and if no template was loaded so far.
  80     Modifications on environments after the first template was loaded
  81     will lead to surprising effects and undefined behavior.
  82
  83     Here the possible initialization parameters:
  84
  85     `block_start_string`
  86         The string marking the begin of a block.  Defaults to ``'{%'``.
  87
  88     `block_end_string`
  89         The string marking the end of a block.  Defaults to ``'%}'``.
  90
  91     `variable_start_string`
  92         The string marking the begin of a print statement.
  93         Defaults to ``'{{'``.
  94
  95     `variable_stop_string`
  96         The string marking the end of a print statement. Defaults to ``'}}'``.
  97
  98     `comment_start_string`
  99         The string marking the begin of a comment.  Defaults to ``'{#'``.
 100
 101     `comment_end_string`
 102         The string marking the end of a comment.  Defaults to ``'#}'``.
 103
 104     `line_statement_prefix`
 105         If given and a string, this will be used as prefix for line based
 106         statements.
 107
 108     `trim_blocks`
 109         If this is set to ``True`` the first newline after a block is
 110         removed (block, not variable tag!).  Defaults to `False`.
 111
 112     `extensions`
 113         List of Jinja extensions to use.  This can either be import paths
 114         as strings or extension classes.
 115
 116     `optimized`
 117         should the optimizer be enabled?  Default is `True`.
 118
 119     `undefined`
 120         :class:`Undefined` or a subclass of it that is used to represent
 121         undefined values in the template.
 122
 123     `finalize`
 124         A callable that finalizes the variable.  Per default no finalizing
 125         is applied.
 126
 127     `autoescape`
 128         If set to true the XML/HTML autoescaping feature is enabled.
 129
 130     `loader`
 131         The template loader for this environment.
 132
 133     `cache_size`
 134         The size of the cache.  Per default this is ``50`` which means that if
 135         more than 50 templates are loaded the loader will clean out the least
 136         recently used template.  If the cache size is set to ``0`` templates are
 137         recompiled all the time, if the cache size is ``-1`` the cache will not
 138         be cleaned.
 139
 140     `auto_reload`
 141         Some loaders load templates from locations where the template sources
 142         may change (ie: file system or database).  If `auto_reload` is set to
 143         `True` (default) every time a template is requested the loader checks
 144         if the source changed and if yes, it will reload the template.  For
 145         higher performance it's possible to disable that.
 146     """
 147
 148     #: if this environment is sandboxed.  Modifying this variable won't make
 149     #: the environment sandboxed though.  For a real sandboxed environment
 150     #: have a look at jinja2.sandbox
 151     sandboxed = False
 152
 153     #: True if the environment is just an overlay
 154     overlay = False
 155
 156     #: the environment this environment is linked to if it is an overlay
 157     linked_to = None
 158
 159     #: shared environments have this set to `True`.  A shared environment
 160     #: must not be modified
 161     shared = False
 162
 163     def __init__(self,
 164                  block_start_string=BLOCK_START_STRING,
 165                  block_end_string=BLOCK_END_STRING,
 166                  variable_start_string=VARIABLE_START_STRING,
 167                  variable_end_string=VARIABLE_END_STRING,
 168                  comment_start_string=COMMENT_START_STRING,
 169                  comment_end_string=COMMENT_END_STRING,
 170                  line_statement_prefix=LINE_STATEMENT_PREFIX,
 171                  trim_blocks=False,
 172                  extensions=(),
 173                  optimized=True,
 174                  undefined=Undefined,
 175                  finalize=None,
 176                  autoescape=False,
 177                  loader=None,
 178                  cache_size=50,
 179                  auto_reload=True):
 180         # !!Important notice!!
 181         #   The constructor accepts quite a few arguments that should be
 182         #   passed by keyword rather than position.  However it's important to
 183         #   not change the order of arguments because it's used at least
 184         #   internally in those cases:
 185         #       -   spontaneus environments (i18n extension and Template)
 186         #       -   unittests
 187         #   If parameter changes are required only add parameters at the end
 188         #   and don't change the arguments (or the defaults!) of the arguments
 189         #   existing already.
 190
 191         # lexer / parser information
 192         self.block_start_string = block_start_string
 193         self.block_end_string = block_end_string
 194         self.variable_start_string = variable_start_string
 195         self.variable_end_string = variable_end_string
 196         self.comment_start_string = comment_start_string
 197         self.comment_end_string = comment_end_string
 198         self.line_statement_prefix = line_statement_prefix
 199         self.trim_blocks = trim_blocks
 200
 201         # runtime information
 202         self.undefined = undefined
 203         self.optimized = optimized
 204         self.finalize = finalize
 205         self.autoescape = autoescape
 206
 207         # defaults
 208         self.filters = DEFAULT_FILTERS.copy()
 209         self.tests = DEFAULT_TESTS.copy()
 210         self.globals = DEFAULT_NAMESPACE.copy()
 211
 212         # set the loader provided
 213         self.loader = loader
 214         self.cache = create_cache(cache_size)
 215         self.auto_reload = auto_reload
 216
 217         # load extensions
 218         self.extensions = load_extensions(self, extensions)
 219
 220         _environment_sanity_check(self)
 221
 222     def overlay(self, block_start_string=missing, block_end_string=missing,
 223                 variable_start_string=missing, variable_end_string=missing,
 224                 comment_start_string=missing, comment_end_string=missing,
 225                 line_statement_prefix=missing, trim_blocks=missing,
 226                 extensions=missing, optimized=missing, undefined=missing,
 227                 finalize=missing, autoescape=missing, loader=missing,
 228                 cache_size=missing, auto_reload=missing):
 229         """Create a new overlay environment that shares all the data with the
 230         current environment except of cache and the overriden attributes.
 231         Extensions cannot be removed for a overlayed environment.  A overlayed
 232         environment automatically gets all the extensions of the environment it
 233         is linked to plus optional extra extensions.
 234
 235         Creating overlays should happen after the initial environment was set
 236         up completely.  Not all attributes are truly linked, some are just
 237         copied over so modifications on the original environment may not shine
 238         through.
 239         """
 240         args = dict(locals())
 241         del args['self'], args['cache_size'], args['extensions']
 242
 243         rv = object.__new__(self.__class__)
 244         rv.__dict__.update(self.__dict__)
 245         rv.overlay = True
 246         rv.linked_to = self
 247
 248         for key, value in args.iteritems():
 249             if value is not missing:
 250                 setattr(rv, key, value)
 251
 252         if cache_size is not missing:
 253             rv.cache = create_cache(cache_size)
 254
 255         rv.extensions = []
 256         for extension in self.extensions:
 257             rv.extensions.append(extension.bind(self))
 258         if extensions is not missing:
 259             rv.extensions.extend(load_extensions(extensions))
 260
 261         return _environment_sanity_check(rv)
 262
 263     @property
 264     def lexer(self):
 265         """Return a fresh lexer for the environment."""
 266         return Lexer(self)
 267
 268     def subscribe(self, obj, argument):
 269         """Get an item or attribute of an object."""
 270         try:
 271             return getattr(obj, str(argument))
 272         except (AttributeError, UnicodeError):
 273             try:
 274                 return obj[argument]
 275             except (TypeError, LookupError):
 276                 return self.undefined(obj=obj, name=argument)
 277
 278     def parse(self, source, filename=None):
 279         """Parse the sourcecode and return the abstract syntax tree.  This
 280         tree of nodes is used by the compiler to convert the template into
 281         executable source- or bytecode.  This is useful for debugging or to
 282         extract information from templates.
 283         """
 284         try:
 285             return Parser(self, source, filename).parse()
 286         except TemplateSyntaxError, e:
 287             exc_type, exc_value, tb = translate_syntax_error(e)
 288             raise exc_type, exc_value, tb
 289
 290     def lex(self, source, name=None):
 291         """Lex the given sourcecode and return a generator that yields
 292         tokens as tuples in the form ``(lineno, token_type, value)``.
 293         """
 294         return self.lexer.tokeniter(source, name)
 295
 296     def compile(self, source, name=None, filename=None, globals=None,
 297                 raw=False):
 298         """Compile a node or template source code.  The `name` parameter is
 299         the load name of the template after it was joined using
 300         :meth:`join_path` if necessary, not the filename on the file system.
 301         the `filename` parameter is the estimated filename of the template on
 302         the file system.  If the template came from a database or memory this
 303         can be omitted.  The `globals` parameter can be used to provide extra
 304         variables at compile time for the template.  In the future the
 305         optimizer will be able to evaluate parts of the template at compile
 306         time based on those variables.
 307
 308         The return value of this method is a python code object.  If the `raw`
 309         parameter is `True` the return value will be a string with python
 310         code equivalent to the bytecode returned otherwise.  This method is
 311         mainly used internally.
 312         """
 313         if isinstance(source, basestring):
 314             source = self.parse(source, filename)
 315         if self.optimized:
 316             node = optimize(source, self, globals or {})
 317         source = generate(node, self, name, filename)
 318         if raw:
 319             return source
 320         if filename is None:
 321             filename = '<template>'
 322         elif isinstance(filename, unicode):
 323             filename = filename.encode('utf-8')
 324         return compile(source, filename, 'exec')
 325
 326     def join_path(self, template, parent):
 327         """Join a template with the parent.  By default all the lookups are
 328         relative to the loader root so this method returns the `template`
 329         parameter unchanged, but if the paths should be relative to the
 330         parent template, this function can be used to calculate the real
 331         template name.
 332
 333         Subclasses may override this method and implement template path
 334         joining here.
 335         """
 336         return template
 337
 338     def get_template(self, name, parent=None, globals=None):
 339         """Load a template from the loader.  If a loader is configured this
 340         method ask the loader for the template and returns a :class:`Template`.
 341         If the `parent` parameter is not `None`, :meth:`join_path` is called
 342         to get the real template name before loading.
 343
 344         The `globals` parameter can be used to provide compile-time globals.
 345         In the future this will allow the optimizer to render parts of the
 346         templates at compile-time.
 347
 348         If the template does not exist a :exc:`TemplateNotFound` exception is
 349         raised.
 350         """
 351         if self.loader is None:
 352             raise TypeError('no loader for this environment specified')
 353         if parent is not None:
 354             name = self.join_path(name, parent)
 355
 356         if self.cache is not None:
 357             template = self.cache.get(name)
 358             if template is not None and (not self.auto_reload or \
 359                                          template.is_up_to_date):
 360                 return template
 361
 362         template = self.loader.load(self, name, self.make_globals(globals))
 363         if self.cache is not None:
 364             self.cache[name] = template
 365         return template
 366
 367     def from_string(self, source, globals=None, template_class=None):
 368         """Load a template from a string.  This parses the source given and
 369         returns a :class:`Template` object.
 370         """
 371         globals = self.make_globals(globals)
 372         cls = template_class or self.template_class
 373         return cls.from_code(self, self.compile(source, globals=globals),
 374                              globals, None)
 375
 376     def make_globals(self, d):
 377         """Return a dict for the globals."""
 378         if d is None:
 379             return self.globals
 380         return dict(self.globals, **d)
 381
 382
 383 class Template(object):
 384     """The central template object.  This class represents a compiled template
 385     and is used to evaluate it.
 386
 387     Normally the template object is generated from an :class:`Environment` but
 388     it also has a constructor that makes it possible to create a template
 389     instance directly using the constructor.  It takes the same arguments as
 390     the environment constructor but it's not possible to specify a loader.
 391
 392     Every template object has a few methods and members that are guaranteed
 393     to exist.  However it's important that a template object should be
 394     considered immutable.  Modifications on the object are not supported.
 395
 396     Template objects created from the constructor rather than an environment
 397     do have an `environment` attribute that points to a temporary environment
 398     that is probably shared with other templates created with the constructor
 399     and compatible settings.
 400
 401     >>> template = Template('Hello {{ name }}!')
 402     >>> template.render(name='John Doe')
 403     u'Hello John Doe!'
 404
 405     >>> stream = template.stream(name='John Doe')
 406     >>> stream.next()
 407     u'Hello John Doe!'
 408     >>> stream.next()
 409     Traceback (most recent call last):
 410         ...
 411     StopIteration
 412     """
 413
 414     def __new__(cls, source,
 415                 block_start_string='{%',
 416                 block_end_string='%}',
 417                 variable_start_string='{{',
 418                 variable_end_string='}}',
 419                 comment_start_string='{#',
 420                 comment_end_string='#}',
 421                 line_statement_prefix=None,
 422                 trim_blocks=False,
 423                 extensions=(),
 424                 optimized=True,
 425                 undefined=Undefined,
 426                 finalize=None,
 427                 autoescape=False):
 428         env = get_spontaneous_environment(
 429             block_start_string, block_end_string, variable_start_string,
 430             variable_end_string, comment_start_string, comment_end_string,
 431             line_statement_prefix, trim_blocks, tuple(extensions), optimized,
 432             undefined, finalize, autoescape, None, 0, False)
 433         return env.from_string(source, template_class=cls)
 434
 435     @classmethod
 436     def from_code(cls, environment, code, globals, uptodate=None):
 437         """Creates a template object from compiled code and the globals.  This
 438         is used by the loaders and environment to create a template object.
 439         """
 440         t = object.__new__(cls)
 441         namespace = {
 442             'environment':          environment,
 443             '__jinja_template__':   t
 444         }
 445         exec code in namespace
 446         t.environment = environment
 447         t.name = namespace['name']
 448         t.filename = code.co_filename
 449         t.root_render_func = namespace['root']
 450         t.blocks = namespace['blocks']
 451         t.globals = globals
 452
 453         # debug and loader helpers
 454         t._debug_info = namespace['debug_info']
 455         t._uptodate = uptodate
 456
 457         return t
 458
 459     def render(self, *args, **kwargs):
 460         """This method accepts the same arguments as the `dict` constructor:
 461         A dict, a dict subclass or some keyword arguments.  If no arguments
 462         are given the context will be empty.  These two calls do the same::
 463
 464             template.render(knights='that say nih')
 465             template.render({'knights': 'that say nih'})
 466
 467         This will return the rendered template as unicode string.
 468         """
 469         try:
 470             return concat(self._generate(*args, **kwargs))
 471         except:
 472             exc_type, exc_value, tb = translate_exception(sys.exc_info())
 473             raise exc_type, exc_value, tb
 474
 475     def stream(self, *args, **kwargs):
 476         """Works exactly like :meth:`generate` but returns a
 477         :class:`TemplateStream`.
 478         """
 479         return TemplateStream(self.generate(*args, **kwargs))
 480
 481     def generate(self, *args, **kwargs):
 482         """For very large templates it can be useful to not render the whole
 483         template at once but evaluate each statement after another and yield
 484         piece for piece.  This method basically does exactly that and returns
 485         a generator that yields one item after another as unicode strings.
 486
 487         It accepts the same arguments as :meth:`render`.
 488         """
 489         try:
 490             for item in self._generate(*args, **kwargs):
 491                 yield item
 492         except:
 493             exc_type, exc_value, tb = translate_exception(sys.exc_info())
 494             raise exc_type, exc_value, tb
 495
 496     def _generate(self, *args, **kwargs):
 497         # assemble the context
 498         context = dict(*args, **kwargs)
 499
 500         # if the environment is using the optimizer locals may never
 501         # override globals as optimizations might have happened
 502         # depending on values of certain globals.  This assertion goes
 503         # away if the python interpreter is started with -O
 504         if __debug__ and self.environment.optimized:
 505             overrides = set(context) & set(self.globals)
 506             if overrides:
 507                 plural = len(overrides) != 1 and 's' or ''
 508                 raise AssertionError('the per template variable%s %s '
 509                                      'override%s global variable%s. '
 510                                      'With an enabled optimizer this '
 511                                      'will lead to unexpected results.' %
 512                     (plural, ', '.join(overrides), plural or ' a', plural))
 513
 514         return self.root_render_func(self.new_context(context))
 515
 516     def new_context(self, vars=None, shared=False):
 517         """Create a new template context for this template.  The vars
 518         provided will be passed to the template.  Per default the globals
 519         are added to the context, if shared is set to `True` the data
 520         provided is used as parent namespace.  This is used to share the
 521         same globals in multiple contexts without consuming more memory.
 522         (This works because the context does not modify the parent dict)
 523         """
 524         if vars is None:
 525             vars = {}
 526         if shared:
 527             parent = vars
 528         else:
 529             parent = dict(self.globals, **vars)
 530         return Context(self.environment, parent, self.name, self.blocks)
 531
 532     def make_module(self, vars=None, shared=False):
 533         """Like the `module` property but always reevaluates the template
 534         and it's possible to provide a context.
 535         """
 536         return TemplateModule(self, self.new_context(vars, shared))
 537
 538     @property
 539     def module(self):
 540         """The template as module.  This is used for imports in the
 541         template runtime but is also useful if one wants to access
 542         exported template variables from the Python layer:
 543
 544         >>> t = Template('{% macro foo() %}42{% endmacro %}23')
 545         >>> unicode(t.module)
 546         u'23'
 547         >>> t.module.foo()
 548         u'42'
 549         """
 550         if hasattr(self, '_module'):
 551             return self._module
 552         self._module = rv = self.make_module()
 553         return rv
 554
 555     def get_corresponding_lineno(self, lineno):
 556         """Return the source line number of a line number in the
 557         generated bytecode as they are not in sync.
 558         """
 559         for template_line, code_line in reversed(self.debug_info):
 560             if code_line <= lineno:
 561                 return template_line
 562         return 1
 563
 564     @property
 565     def is_up_to_date(self):
 566         """If this variable is `False` there is a newer version available."""
 567         if self._uptodate is None:
 568             return True
 569         return self._uptodate()
 570
 571     @property
 572     def debug_info(self):
 573         """The debug info mapping."""
 574         return [tuple(map(int, x.split('='))) for x in
 575                 self._debug_info.split('&')]
 576
 577     def __repr__(self):
 578         if self.name is None:
 579             name = 'memory:%x' % id(self)
 580         else:
 581             name = repr(self.name)
 582         return '<%s %s>' % (self.__class__.__name__, name)
 583
 584
 585 class TemplateModule(object):
 586     """Represents an imported template.  All the exported names of the
 587     template are available as attributes on this object.  Additionally
 588     converting it into an unicode- or bytestrings renders the contents.
 589     """
 590
 591     def __init__(self, template, context):
 592         # don't alter this attribute unless you change it in the
 593         # compiler too.  The Include without context passing directly
 594         # uses the mangled name.  The reason why we use a mangled one
 595         # is to avoid name clashes with macros with those names.
 596         self.__body_stream = tuple(template.root_render_func(context))
 597         self.__dict__.update(context.get_exported())
 598         self.__name__ = template.name
 599
 600     __html__ = lambda x: Markup(concat(x.__body_stream))
 601     __unicode__ = lambda x: unicode(concat(x.__body_stream))
 602
 603     def __str__(self):
 604         return unicode(self).encode('utf-8')
 605
 606     def __repr__(self):
 607         if self.__name__ is None:
 608             name = 'memory:%x' % id(self)
 609         else:
 610             name = repr(self.name)
 611         return '<%s %s>' % (self.__class__.__name__, name)
 612
 613
 614 class TemplateStream(object):
 615     """A template stream works pretty much like an ordinary python generator
 616     but it can buffer multiple items to reduce the number of total iterations.
 617     Per default the output is unbuffered which means that for every unbuffered
 618     instruction in the template one unicode string is yielded.
 619
 620     If buffering is enabled with a buffer size of 5, five items are combined
 621     into a new unicode string.  This is mainly useful if you are streaming
 622     big templates to a client via WSGI which flushes after each iteration.
 623     """
 624
 625     def __init__(self, gen):
 626         self._gen = gen
 627         self._next = gen.next
 628         self.buffered = False
 629
 630     def disable_buffering(self):
 631         """Disable the output buffering."""
 632         self._next = self._gen.next
 633         self.buffered = False
 634
 635     def enable_buffering(self, size=5):
 636         """Enable buffering.  Buffer `size` items before yielding them."""
 637         if size <= 1:
 638             raise ValueError('buffer size too small')
 639
 640         def generator():
 641             buf = []
 642             c_size = 0
 643             push = buf.append
 644             next = self._gen.next
 645
 646             while 1:
 647                 try:
 648                     while c_size < size:
 649                         push(next())
 650                         c_size += 1
 651                 except StopIteration:
 652                     if not c_size:
 653                         return
 654                 yield concat(buf)
 655                 del buf[:]
 656                 c_size = 0
 657
 658         self.buffered = True
 659         self._next = generator().next
 660
 661     def __iter__(self):
 662         return self
 663
 664     def next(self):
 665         return self._next()
 666
 667
 668 # hook in default template class.  if anyone reads this comment: ignore that
 669 # it's possible to use custom templates ;-)
 670 Environment.template_class = Template