1 # -*- coding: utf-8 -*-
6 Provides a class that holds runtime and parsing time options.
8 :copyright: (c) 2010 by the Jinja Team.
9 :license: BSD, see LICENSE for more details.
12 from jinja2 import nodes
13 from jinja2.defaults import *
14 from jinja2.lexer import get_lexer, TokenStream
15 from jinja2.parser import Parser
16 from jinja2.optimizer import optimize
17 from jinja2.compiler import generate
18 from jinja2.runtime import Undefined, new_context
19 from jinja2.exceptions import TemplateSyntaxError, TemplateNotFound, \
21 from jinja2.utils import import_string, LRUCache, Markup, missing, \
22 concat, consume, internalcode
25 # for direct template usage we have up to ten living environments
26 _spontaneous_environments = LRUCache(10)
28 # the function to create jinja traceback objects. This is dynamically
29 # imported on the first exception in the exception handler.
30 _make_traceback = None
33 def get_spontaneous_environment(*args):
34 """Return a new spontaneous environment. A spontaneous environment is an
35 unnamed and unaccessible (in theory) environment that is used for
36 templates generated from a string and not from the file system.
39 env = _spontaneous_environments.get(args)
41 return Environment(*args)
44 _spontaneous_environments[args] = env = Environment(*args)
49 def create_cache(size):
50 """Return the cache class for the given size."""
58 def copy_cache(cache):
59 """Create an empty copy of the given cache."""
62 elif type(cache) is dict:
64 return LRUCache(cache.capacity)
67 def load_extensions(environment, extensions):
68 """Load the extensions from the list and bind it to the environment.
69 Returns a dict of instanciated environments.
72 for extension in extensions:
73 if isinstance(extension, basestring):
74 extension = import_string(extension)
75 result[extension.identifier] = extension(environment)
79 def _environment_sanity_check(environment):
80 """Perform a sanity check on the environment."""
81 assert issubclass(environment.undefined, Undefined), 'undefined must ' \
82 'be a subclass of undefined because filters depend on it.'
83 assert environment.block_start_string != \
84 environment.variable_start_string != \
85 environment.comment_start_string, 'block, variable and comment ' \
86 'start strings must be different'
87 assert environment.newline_sequence in ('\r', '\r\n', '\n'), \
88 'newline_sequence set to unknown line ending string.'
92 class Environment(object):
93 r"""The core component of Jinja is the `Environment`. It contains
94 important shared variables like configuration, filters, tests,
95 globals and others. Instances of this class may be modified if
96 they are not shared and if no template was loaded so far.
97 Modifications on environments after the first template was loaded
98 will lead to surprising effects and undefined behavior.
100 Here the possible initialization parameters:
103 The string marking the begin of a block. Defaults to ``'{%'``.
106 The string marking the end of a block. Defaults to ``'%}'``.
108 `variable_start_string`
109 The string marking the begin of a print statement.
110 Defaults to ``'{{'``.
112 `variable_end_string`
113 The string marking the end of a print statement. Defaults to
116 `comment_start_string`
117 The string marking the begin of a comment. Defaults to ``'{#'``.
120 The string marking the end of a comment. Defaults to ``'#}'``.
122 `line_statement_prefix`
123 If given and a string, this will be used as prefix for line based
124 statements. See also :ref:`line-statements`.
126 `line_comment_prefix`
127 If given and a string, this will be used as prefix for line based
128 based comments. See also :ref:`line-statements`.
130 .. versionadded:: 2.2
133 If this is set to ``True`` the first newline after a block is
134 removed (block, not variable tag!). Defaults to `False`.
137 The sequence that starts a newline. Must be one of ``'\r'``,
138 ``'\n'`` or ``'\r\n'``. The default is ``'\n'`` which is a
139 useful default for Linux and OS X systems as well as web
143 List of Jinja extensions to use. This can either be import paths
144 as strings or extension classes. For more information have a
145 look at :ref:`the extensions documentation <jinja-extensions>`.
148 should the optimizer be enabled? Default is `True`.
151 :class:`Undefined` or a subclass of it that is used to represent
152 undefined values in the template.
155 A callable that can be used to process the result of a variable
156 expression before it is output. For example one can convert
157 `None` implicitly into an empty string here.
160 If set to true the XML/HTML autoescaping feature is enabled.
161 For more details about auto escaping see
162 :class:`~jinja2.utils.Markup`.
165 The template loader for this environment.
168 The size of the cache. Per default this is ``50`` which means
169 that if more than 50 templates are loaded the loader will clean
170 out the least recently used template. If the cache size is set to
171 ``0`` templates are recompiled all the time, if the cache size is
172 ``-1`` the cache will not be cleaned.
175 Some loaders load templates from locations where the template
176 sources may change (ie: file system or database). If
177 `auto_reload` is set to `True` (default) every time a template is
178 requested the loader checks if the source changed and if yes, it
179 will reload the template. For higher performance it's possible to
183 If set to a bytecode cache object, this object will provide a
184 cache for the internal Jinja bytecode so that templates don't
185 have to be parsed if they were not changed.
187 See :ref:`bytecode-cache` for more information.
190 #: if this environment is sandboxed. Modifying this variable won't make
191 #: the environment sandboxed though. For a real sandboxed environment
192 #: have a look at jinja2.sandbox
195 #: True if the environment is just an overlay
198 #: the environment this environment is linked to if it is an overlay
201 #: shared environments have this set to `True`. A shared environment
202 #: must not be modified
205 #: these are currently EXPERIMENTAL undocumented features.
206 exception_handler = None
207 exception_formatter = None
210 block_start_string=BLOCK_START_STRING,
211 block_end_string=BLOCK_END_STRING,
212 variable_start_string=VARIABLE_START_STRING,
213 variable_end_string=VARIABLE_END_STRING,
214 comment_start_string=COMMENT_START_STRING,
215 comment_end_string=COMMENT_END_STRING,
216 line_statement_prefix=LINE_STATEMENT_PREFIX,
217 line_comment_prefix=LINE_COMMENT_PREFIX,
218 trim_blocks=TRIM_BLOCKS,
219 newline_sequence=NEWLINE_SEQUENCE,
228 bytecode_cache=None):
229 # !!Important notice!!
230 # The constructor accepts quite a few arguments that should be
231 # passed by keyword rather than position. However it's important to
232 # not change the order of arguments because it's used at least
233 # internally in those cases:
234 # - spontaneus environments (i18n extension and Template)
236 # If parameter changes are required only add parameters at the end
237 # and don't change the arguments (or the defaults!) of the arguments
240 # lexer / parser information
241 self.block_start_string = block_start_string
242 self.block_end_string = block_end_string
243 self.variable_start_string = variable_start_string
244 self.variable_end_string = variable_end_string
245 self.comment_start_string = comment_start_string
246 self.comment_end_string = comment_end_string
247 self.line_statement_prefix = line_statement_prefix
248 self.line_comment_prefix = line_comment_prefix
249 self.trim_blocks = trim_blocks
250 self.newline_sequence = newline_sequence
252 # runtime information
253 self.undefined = undefined
254 self.optimized = optimized
255 self.finalize = finalize
256 self.autoescape = autoescape
259 self.filters = DEFAULT_FILTERS.copy()
260 self.tests = DEFAULT_TESTS.copy()
261 self.globals = DEFAULT_NAMESPACE.copy()
263 # set the loader provided
265 self.bytecode_cache = None
266 self.cache = create_cache(cache_size)
267 self.bytecode_cache = bytecode_cache
268 self.auto_reload = auto_reload
271 self.extensions = load_extensions(self, extensions)
273 _environment_sanity_check(self)
275 def extend(self, **attributes):
276 """Add the items to the instance of the environment if they do not exist
277 yet. This is used by :ref:`extensions <writing-extensions>` to register
278 callbacks and configuration values without breaking inheritance.
280 for key, value in attributes.iteritems():
281 if not hasattr(self, key):
282 setattr(self, key, value)
284 def overlay(self, block_start_string=missing, block_end_string=missing,
285 variable_start_string=missing, variable_end_string=missing,
286 comment_start_string=missing, comment_end_string=missing,
287 line_statement_prefix=missing, line_comment_prefix=missing,
288 trim_blocks=missing, extensions=missing, optimized=missing,
289 undefined=missing, finalize=missing, autoescape=missing,
290 loader=missing, cache_size=missing, auto_reload=missing,
291 bytecode_cache=missing):
292 """Create a new overlay environment that shares all the data with the
293 current environment except of cache and the overridden attributes.
294 Extensions cannot be removed for an overlayed environment. An overlayed
295 environment automatically gets all the extensions of the environment it
296 is linked to plus optional extra extensions.
298 Creating overlays should happen after the initial environment was set
299 up completely. Not all attributes are truly linked, some are just
300 copied over so modifications on the original environment may not shine
303 args = dict(locals())
304 del args['self'], args['cache_size'], args['extensions']
306 rv = object.__new__(self.__class__)
307 rv.__dict__.update(self.__dict__)
311 for key, value in args.iteritems():
312 if value is not missing:
313 setattr(rv, key, value)
315 if cache_size is not missing:
316 rv.cache = create_cache(cache_size)
318 rv.cache = copy_cache(self.cache)
321 for key, value in self.extensions.iteritems():
322 rv.extensions[key] = value.bind(rv)
323 if extensions is not missing:
324 rv.extensions.update(load_extensions(extensions))
326 return _environment_sanity_check(rv)
328 lexer = property(get_lexer, doc="The lexer for this environment.")
330 def getitem(self, obj, argument):
331 """Get an item or attribute of an object but prefer the item."""
334 except (TypeError, LookupError):
335 if isinstance(argument, basestring):
342 return getattr(obj, attr)
343 except AttributeError:
345 return self.undefined(obj=obj, name=argument)
347 def getattr(self, obj, attribute):
348 """Get an item or attribute of an object but prefer the attribute.
349 Unlike :meth:`getitem` the attribute *must* be a bytestring.
352 return getattr(obj, attribute)
353 except AttributeError:
356 return obj[attribute]
357 except (TypeError, LookupError, AttributeError):
358 return self.undefined(obj=obj, name=attribute)
361 def parse(self, source, name=None, filename=None):
362 """Parse the sourcecode and return the abstract syntax tree. This
363 tree of nodes is used by the compiler to convert the template into
364 executable source- or bytecode. This is useful for debugging or to
365 extract information from templates.
367 If you are :ref:`developing Jinja2 extensions <writing-extensions>`
368 this gives you a good overview of the node tree generated.
371 return self._parse(source, name, filename)
372 except TemplateSyntaxError:
373 exc_info = sys.exc_info()
374 self.handle_exception(exc_info, source_hint=source)
376 def _parse(self, source, name, filename):
377 """Internal parsing function used by `parse` and `compile`."""
378 if isinstance(filename, unicode):
379 filename = filename.encode('utf-8')
380 return Parser(self, source, name, filename).parse()
382 def lex(self, source, name=None, filename=None):
383 """Lex the given sourcecode and return a generator that yields
384 tokens as tuples in the form ``(lineno, token_type, value)``.
385 This can be useful for :ref:`extension development <writing-extensions>`
386 and debugging templates.
388 This does not perform preprocessing. If you want the preprocessing
389 of the extensions to be applied you have to filter source through
390 the :meth:`preprocess` method.
392 source = unicode(source)
394 return self.lexer.tokeniter(source, name, filename)
395 except TemplateSyntaxError:
396 exc_info = sys.exc_info()
397 self.handle_exception(exc_info, source_hint=source)
399 def preprocess(self, source, name=None, filename=None):
400 """Preprocesses the source with all extensions. This is automatically
401 called for all parsing and compiling methods but *not* for :meth:`lex`
402 because there you usually only want the actual source tokenized.
404 return reduce(lambda s, e: e.preprocess(s, name, filename),
405 self.extensions.itervalues(), unicode(source))
407 def _tokenize(self, source, name, filename=None, state=None):
408 """Called by the parser to do the preprocessing and filtering
409 for all the extensions. Returns a :class:`~jinja2.lexer.TokenStream`.
411 source = self.preprocess(source, name, filename)
412 stream = self.lexer.tokenize(source, name, filename, state)
413 for ext in self.extensions.itervalues():
414 stream = ext.filter_stream(stream)
415 if not isinstance(stream, TokenStream):
416 stream = TokenStream(stream, name, filename)
420 def compile(self, source, name=None, filename=None, raw=False):
421 """Compile a node or template source code. The `name` parameter is
422 the load name of the template after it was joined using
423 :meth:`join_path` if necessary, not the filename on the file system.
424 the `filename` parameter is the estimated filename of the template on
425 the file system. If the template came from a database or memory this
428 The return value of this method is a python code object. If the `raw`
429 parameter is `True` the return value will be a string with python
430 code equivalent to the bytecode returned otherwise. This method is
431 mainly used internally.
435 if isinstance(source, basestring):
437 source = self._parse(source, name, filename)
439 source = optimize(source, self)
440 source = generate(source, self, name, filename)
444 filename = '<template>'
445 elif isinstance(filename, unicode):
446 filename = filename.encode('utf-8')
447 return compile(source, filename, 'exec')
448 except TemplateSyntaxError:
449 exc_info = sys.exc_info()
450 self.handle_exception(exc_info, source_hint=source)
452 def compile_expression(self, source, undefined_to_none=True):
453 """A handy helper method that returns a callable that accepts keyword
454 arguments that appear as variables in the expression. If called it
455 returns the result of the expression.
457 This is useful if applications want to use the same rules as Jinja
458 in template "configuration files" or similar situations.
462 >>> env = Environment()
463 >>> expr = env.compile_expression('foo == 42')
469 Per default the return value is converted to `None` if the
470 expression returns an undefined value. This can be changed
471 by setting `undefined_to_none` to `False`.
473 >>> env.compile_expression('var')() is None
475 >>> env.compile_expression('var', undefined_to_none=False)()
478 .. versionadded:: 2.1
480 parser = Parser(self, source, state='variable')
483 expr = parser.parse_expression()
484 if not parser.stream.eos:
485 raise TemplateSyntaxError('chunk after expression',
486 parser.stream.current.lineno,
488 except TemplateSyntaxError:
489 exc_info = sys.exc_info()
490 if exc_info is not None:
491 self.handle_exception(exc_info, source_hint=source)
492 body = [nodes.Assign(nodes.Name('result', 'store'), expr, lineno=1)]
493 template = self.from_string(nodes.Template(body, lineno=1))
494 return TemplateExpression(template, undefined_to_none)
496 def handle_exception(self, exc_info=None, rendered=False, source_hint=None):
497 """Exception handling helper. This is used internally to either raise
498 rewritten exceptions or return a rendered traceback for the template.
500 global _make_traceback
502 exc_info = sys.exc_info()
504 # the debugging module is imported when it's used for the first time.
505 # we're doing a lot of stuff there and for applications that do not
506 # get any exceptions in template rendering there is no need to load
508 if _make_traceback is None:
509 from jinja2.debug import make_traceback as _make_traceback
510 traceback = _make_traceback(exc_info, source_hint)
511 if rendered and self.exception_formatter is not None:
512 return self.exception_formatter(traceback)
513 if self.exception_handler is not None:
514 self.exception_handler(traceback)
515 exc_type, exc_value, tb = traceback.standard_exc_info
516 raise exc_type, exc_value, tb
518 def join_path(self, template, parent):
519 """Join a template with the parent. By default all the lookups are
520 relative to the loader root so this method returns the `template`
521 parameter unchanged, but if the paths should be relative to the
522 parent template, this function can be used to calculate the real
525 Subclasses may override this method and implement template path
531 def _load_template(self, name, globals):
532 if self.loader is None:
533 raise TypeError('no loader for this environment specified')
534 if self.cache is not None:
535 template = self.cache.get(name)
536 if template is not None and (not self.auto_reload or \
537 template.is_up_to_date):
539 template = self.loader.load(self, name, globals)
540 if self.cache is not None:
541 self.cache[name] = template
545 def get_template(self, name, parent=None, globals=None):
546 """Load a template from the loader. If a loader is configured this
547 method ask the loader for the template and returns a :class:`Template`.
548 If the `parent` parameter is not `None`, :meth:`join_path` is called
549 to get the real template name before loading.
551 The `globals` parameter can be used to provide template wide globals.
552 These variables are available in the context at render time.
554 If the template does not exist a :exc:`TemplateNotFound` exception is
557 if parent is not None:
558 name = self.join_path(name, parent)
559 return self._load_template(name, self.make_globals(globals))
562 def select_template(self, names, parent=None, globals=None):
563 """Works like :meth:`get_template` but tries a number of templates
564 before it fails. If it cannot find any of the templates, it will
565 raise a :exc:`TemplatesNotFound` exception.
567 .. versionadded:: 2.3
570 raise TemplatesNotFound(message=u'Tried to select from an empty list '
572 globals = self.make_globals(globals)
574 if parent is not None:
575 name = self.join_path(name, parent)
577 return self._load_template(name, globals)
578 except TemplateNotFound:
580 raise TemplatesNotFound(names)
583 def get_or_select_template(self, template_name_or_list,
584 parent=None, globals=None):
586 Does a typecheck and dispatches to :meth:`select_template` if an
587 iterable of template names is given, otherwise to :meth:`get_template`.
589 .. versionadded:: 2.3
591 if isinstance(template_name_or_list, basestring):
592 return self.get_template(template_name_or_list, parent, globals)
593 return self.select_template(template_name_or_list, parent, globals)
595 def from_string(self, source, globals=None, template_class=None):
596 """Load a template from a string. This parses the source given and
597 returns a :class:`Template` object.
599 globals = self.make_globals(globals)
600 cls = template_class or self.template_class
601 return cls.from_code(self, self.compile(source), globals, None)
603 def make_globals(self, d):
604 """Return a dict for the globals."""
607 return dict(self.globals, **d)
610 class Template(object):
611 """The central template object. This class represents a compiled template
612 and is used to evaluate it.
614 Normally the template object is generated from an :class:`Environment` but
615 it also has a constructor that makes it possible to create a template
616 instance directly using the constructor. It takes the same arguments as
617 the environment constructor but it's not possible to specify a loader.
619 Every template object has a few methods and members that are guaranteed
620 to exist. However it's important that a template object should be
621 considered immutable. Modifications on the object are not supported.
623 Template objects created from the constructor rather than an environment
624 do have an `environment` attribute that points to a temporary environment
625 that is probably shared with other templates created with the constructor
626 and compatible settings.
628 >>> template = Template('Hello {{ name }}!')
629 >>> template.render(name='John Doe')
632 >>> stream = template.stream(name='John Doe')
636 Traceback (most recent call last):
641 def __new__(cls, source,
642 block_start_string=BLOCK_START_STRING,
643 block_end_string=BLOCK_END_STRING,
644 variable_start_string=VARIABLE_START_STRING,
645 variable_end_string=VARIABLE_END_STRING,
646 comment_start_string=COMMENT_START_STRING,
647 comment_end_string=COMMENT_END_STRING,
648 line_statement_prefix=LINE_STATEMENT_PREFIX,
649 line_comment_prefix=LINE_COMMENT_PREFIX,
650 trim_blocks=TRIM_BLOCKS,
651 newline_sequence=NEWLINE_SEQUENCE,
657 env = get_spontaneous_environment(
658 block_start_string, block_end_string, variable_start_string,
659 variable_end_string, comment_start_string, comment_end_string,
660 line_statement_prefix, line_comment_prefix, trim_blocks,
661 newline_sequence, frozenset(extensions), optimized, undefined,
662 finalize, autoescape, None, 0, False, None)
663 return env.from_string(source, template_class=cls)
666 def from_code(cls, environment, code, globals, uptodate=None):
667 """Creates a template object from compiled code and the globals. This
668 is used by the loaders and environment to create a template object.
670 t = object.__new__(cls)
672 'environment': environment,
673 '__jinja_template__': t
675 exec code in namespace
676 t.environment = environment
678 t.name = namespace['name']
679 t.filename = code.co_filename
680 t.blocks = namespace['blocks']
682 # render function and module
683 t.root_render_func = namespace['root']
686 # debug and loader helpers
687 t._debug_info = namespace['debug_info']
688 t._uptodate = uptodate
692 def render(self, *args, **kwargs):
693 """This method accepts the same arguments as the `dict` constructor:
694 A dict, a dict subclass or some keyword arguments. If no arguments
695 are given the context will be empty. These two calls do the same::
697 template.render(knights='that say nih')
698 template.render({'knights': 'that say nih'})
700 This will return the rendered template as unicode string.
702 vars = dict(*args, **kwargs)
704 return concat(self.root_render_func(self.new_context(vars)))
706 exc_info = sys.exc_info()
707 return self.environment.handle_exception(exc_info, True)
709 def stream(self, *args, **kwargs):
710 """Works exactly like :meth:`generate` but returns a
711 :class:`TemplateStream`.
713 return TemplateStream(self.generate(*args, **kwargs))
715 def generate(self, *args, **kwargs):
716 """For very large templates it can be useful to not render the whole
717 template at once but evaluate each statement after another and yield
718 piece for piece. This method basically does exactly that and returns
719 a generator that yields one item after another as unicode strings.
721 It accepts the same arguments as :meth:`render`.
723 vars = dict(*args, **kwargs)
725 for event in self.root_render_func(self.new_context(vars)):
728 exc_info = sys.exc_info()
731 yield self.environment.handle_exception(exc_info, True)
733 def new_context(self, vars=None, shared=False, locals=None):
734 """Create a new :class:`Context` for this template. The vars
735 provided will be passed to the template. Per default the globals
736 are added to the context. If shared is set to `True` the data
737 is passed as it to the context without adding the globals.
739 `locals` can be a dict of local variables for internal usage.
741 return new_context(self.environment, self.name, self.blocks,
742 vars, shared, self.globals, locals)
744 def make_module(self, vars=None, shared=False, locals=None):
745 """This method works like the :attr:`module` attribute when called
746 without arguments but it will evaluate the template on every call
747 rather than caching it. It's also possible to provide
748 a dict which is then used as context. The arguments are the same
749 as for the :meth:`new_context` method.
751 return TemplateModule(self, self.new_context(vars, shared, locals))
755 """The template as module. This is used for imports in the
756 template runtime but is also useful if one wants to access
757 exported template variables from the Python layer:
759 >>> t = Template('{% macro foo() %}42{% endmacro %}23')
760 >>> unicode(t.module)
765 if self._module is not None:
767 self._module = rv = self.make_module()
770 def get_corresponding_lineno(self, lineno):
771 """Return the source line number of a line number in the
772 generated bytecode as they are not in sync.
774 for template_line, code_line in reversed(self.debug_info):
775 if code_line <= lineno:
780 def is_up_to_date(self):
781 """If this variable is `False` there is a newer version available."""
782 if self._uptodate is None:
784 return self._uptodate()
787 def debug_info(self):
788 """The debug info mapping."""
789 return [tuple(map(int, x.split('='))) for x in
790 self._debug_info.split('&')]
793 if self.name is None:
794 name = 'memory:%x' % id(self)
796 name = repr(self.name)
797 return '<%s %s>' % (self.__class__.__name__, name)
800 class TemplateModule(object):
801 """Represents an imported template. All the exported names of the
802 template are available as attributes on this object. Additionally
803 converting it into an unicode- or bytestrings renders the contents.
806 def __init__(self, template, context):
807 self._body_stream = list(template.root_render_func(context))
808 self.__dict__.update(context.get_exported())
809 self.__name__ = template.name
812 return Markup(concat(self._body_stream))
815 return unicode(self).encode('utf-8')
817 def __unicode__(self):
818 return concat(self._body_stream)
821 if self.__name__ is None:
822 name = 'memory:%x' % id(self)
824 name = repr(self.__name__)
825 return '<%s %s>' % (self.__class__.__name__, name)
828 class TemplateExpression(object):
829 """The :meth:`jinja2.Environment.compile_expression` method returns an
830 instance of this object. It encapsulates the expression-like access
831 to the template with an expression it wraps.
834 def __init__(self, template, undefined_to_none):
835 self._template = template
836 self._undefined_to_none = undefined_to_none
838 def __call__(self, *args, **kwargs):
839 context = self._template.new_context(dict(*args, **kwargs))
840 consume(self._template.root_render_func(context))
841 rv = context.vars['result']
842 if self._undefined_to_none and isinstance(rv, Undefined):
847 class TemplateStream(object):
848 """A template stream works pretty much like an ordinary python generator
849 but it can buffer multiple items to reduce the number of total iterations.
850 Per default the output is unbuffered which means that for every unbuffered
851 instruction in the template one unicode string is yielded.
853 If buffering is enabled with a buffer size of 5, five items are combined
854 into a new unicode string. This is mainly useful if you are streaming
855 big templates to a client via WSGI which flushes after each iteration.
858 def __init__(self, gen):
860 self.disable_buffering()
862 def dump(self, fp, encoding=None, errors='strict'):
863 """Dump the complete stream into a file or file-like object.
864 Per default unicode strings are written, if you want to encode
865 before writing specifiy an `encoding`.
869 Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
872 if isinstance(fp, basestring):
876 if encoding is not None:
877 iterable = (x.encode(encoding, errors) for x in self)
880 if hasattr(fp, 'writelines'):
881 fp.writelines(iterable)
883 for item in iterable:
889 def disable_buffering(self):
890 """Disable the output buffering."""
891 self._next = self._gen.next
892 self.buffered = False
894 def enable_buffering(self, size=5):
895 """Enable buffering. Buffer `size` items before yielding them."""
897 raise ValueError('buffer size too small')
911 except StopIteration:
919 self._next = generator(self._gen.next).next
928 # hook in default template class. if anyone reads this comment: ignore that
929 # it's possible to use custom templates ;-)
930 Environment.template_class = Template