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