Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/jinja2/environment.py: 27%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Classes for managing templates and their runtime and compile time
2options.
3"""
5import os
6import typing
7import typing as t
8import weakref
9from collections import ChainMap
10from functools import lru_cache
11from functools import partial
12from functools import reduce
13from types import CodeType
15from markupsafe import Markup
17from . import nodes
18from .compiler import CodeGenerator
19from .compiler import generate
20from .defaults import BLOCK_END_STRING
21from .defaults import BLOCK_START_STRING
22from .defaults import COMMENT_END_STRING
23from .defaults import COMMENT_START_STRING
24from .defaults import DEFAULT_FILTERS # type: ignore[attr-defined]
25from .defaults import DEFAULT_NAMESPACE
26from .defaults import DEFAULT_POLICIES
27from .defaults import DEFAULT_TESTS # type: ignore[attr-defined]
28from .defaults import KEEP_TRAILING_NEWLINE
29from .defaults import LINE_COMMENT_PREFIX
30from .defaults import LINE_STATEMENT_PREFIX
31from .defaults import LSTRIP_BLOCKS
32from .defaults import NEWLINE_SEQUENCE
33from .defaults import TRIM_BLOCKS
34from .defaults import VARIABLE_END_STRING
35from .defaults import VARIABLE_START_STRING
36from .exceptions import TemplateNotFound
37from .exceptions import TemplateRuntimeError
38from .exceptions import TemplatesNotFound
39from .exceptions import TemplateSyntaxError
40from .exceptions import UndefinedError
41from .lexer import get_lexer
42from .lexer import Lexer
43from .lexer import TokenStream
44from .nodes import EvalContext
45from .parser import Parser
46from .runtime import Context
47from .runtime import new_context
48from .runtime import Undefined
49from .utils import _PassArg
50from .utils import concat
51from .utils import consume
52from .utils import import_string
53from .utils import internalcode
54from .utils import LRUCache
55from .utils import missing
57if t.TYPE_CHECKING:
58 import typing_extensions as te
60 from .bccache import BytecodeCache
61 from .ext import Extension
62 from .loaders import BaseLoader
64_env_bound = t.TypeVar("_env_bound", bound="Environment")
67# for direct template usage we have up to ten living environments
68@lru_cache(maxsize=10)
69def get_spontaneous_environment(cls: t.Type[_env_bound], *args: t.Any) -> _env_bound:
70 """Return a new spontaneous environment. A spontaneous environment
71 is used for templates created directly rather than through an
72 existing environment.
74 :param cls: Environment class to create.
75 :param args: Positional arguments passed to environment.
76 """
77 env = cls(*args)
78 env.shared = True
79 return env
82def create_cache(
83 size: int,
84) -> t.Optional[t.MutableMapping[t.Tuple["weakref.ref[t.Any]", str], "Template"]]:
85 """Return the cache class for the given size."""
86 if size == 0:
87 return None
89 if size < 0:
90 return {}
92 return LRUCache(size) # type: ignore
95def copy_cache(
96 cache: t.Optional[t.MutableMapping[t.Any, t.Any]],
97) -> t.Optional[t.MutableMapping[t.Tuple["weakref.ref[t.Any]", str], "Template"]]:
98 """Create an empty copy of the given cache."""
99 if cache is None:
100 return None
102 if type(cache) is dict: # noqa E721
103 return {}
105 return LRUCache(cache.capacity) # type: ignore
108def load_extensions(
109 environment: "Environment",
110 extensions: t.Sequence[t.Union[str, t.Type["Extension"]]],
111) -> t.Dict[str, "Extension"]:
112 """Load the extensions from the list and bind it to the environment.
113 Returns a dict of instantiated extensions.
114 """
115 result = {}
117 for extension in extensions:
118 if isinstance(extension, str):
119 extension = t.cast(t.Type["Extension"], import_string(extension))
121 result[extension.identifier] = extension(environment)
123 return result
126def _environment_config_check(environment: _env_bound) -> _env_bound:
127 """Perform a sanity check on the environment."""
128 assert issubclass(
129 environment.undefined, Undefined
130 ), "'undefined' must be a subclass of 'jinja2.Undefined'."
131 assert (
132 environment.block_start_string
133 != environment.variable_start_string
134 != environment.comment_start_string
135 ), "block, variable and comment start strings must be different."
136 assert environment.newline_sequence in {
137 "\r",
138 "\r\n",
139 "\n",
140 }, "'newline_sequence' must be one of '\\n', '\\r\\n', or '\\r'."
141 return environment
144class Environment:
145 r"""The core component of Jinja is the `Environment`. It contains
146 important shared variables like configuration, filters, tests,
147 globals and others. Instances of this class may be modified if
148 they are not shared and if no template was loaded so far.
149 Modifications on environments after the first template was loaded
150 will lead to surprising effects and undefined behavior.
152 Here are the possible initialization parameters:
154 `block_start_string`
155 The string marking the beginning of a block. Defaults to ``'{%'``.
157 `block_end_string`
158 The string marking the end of a block. Defaults to ``'%}'``.
160 `variable_start_string`
161 The string marking the beginning of a print statement.
162 Defaults to ``'{{'``.
164 `variable_end_string`
165 The string marking the end of a print statement. Defaults to
166 ``'}}'``.
168 `comment_start_string`
169 The string marking the beginning of a comment. Defaults to ``'{#'``.
171 `comment_end_string`
172 The string marking the end of a comment. Defaults to ``'#}'``.
174 `line_statement_prefix`
175 If given and a string, this will be used as prefix for line based
176 statements. See also :ref:`line-statements`.
178 `line_comment_prefix`
179 If given and a string, this will be used as prefix for line based
180 comments. See also :ref:`line-statements`.
182 .. versionadded:: 2.2
184 `trim_blocks`
185 If this is set to ``True`` the first newline after a block is
186 removed (block, not variable tag!). Defaults to `False`.
188 `lstrip_blocks`
189 If this is set to ``True`` leading spaces and tabs are stripped
190 from the start of a line to a block. Defaults to `False`.
192 `newline_sequence`
193 The sequence that starts a newline. Must be one of ``'\r'``,
194 ``'\n'`` or ``'\r\n'``. The default is ``'\n'`` which is a
195 useful default for Linux and OS X systems as well as web
196 applications.
198 `keep_trailing_newline`
199 Preserve the trailing newline when rendering templates.
200 The default is ``False``, which causes a single newline,
201 if present, to be stripped from the end of the template.
203 .. versionadded:: 2.7
205 `extensions`
206 List of Jinja extensions to use. This can either be import paths
207 as strings or extension classes. For more information have a
208 look at :ref:`the extensions documentation <jinja-extensions>`.
210 `optimized`
211 should the optimizer be enabled? Default is ``True``.
213 `undefined`
214 :class:`Undefined` or a subclass of it that is used to represent
215 undefined values in the template.
217 `finalize`
218 A callable that can be used to process the result of a variable
219 expression before it is output. For example one can convert
220 ``None`` implicitly into an empty string here.
222 `autoescape`
223 If set to ``True`` the XML/HTML autoescaping feature is enabled by
224 default. For more details about autoescaping see
225 :class:`~markupsafe.Markup`. As of Jinja 2.4 this can also
226 be a callable that is passed the template name and has to
227 return ``True`` or ``False`` depending on autoescape should be
228 enabled by default.
230 .. versionchanged:: 2.4
231 `autoescape` can now be a function
233 `loader`
234 The template loader for this environment.
236 `cache_size`
237 The size of the cache. Per default this is ``400`` which means
238 that if more than 400 templates are loaded the loader will clean
239 out the least recently used template. If the cache size is set to
240 ``0`` templates are recompiled all the time, if the cache size is
241 ``-1`` the cache will not be cleaned.
243 .. versionchanged:: 2.8
244 The cache size was increased to 400 from a low 50.
246 `auto_reload`
247 Some loaders load templates from locations where the template
248 sources may change (ie: file system or database). If
249 ``auto_reload`` is set to ``True`` (default) every time a template is
250 requested the loader checks if the source changed and if yes, it
251 will reload the template. For higher performance it's possible to
252 disable that.
254 `bytecode_cache`
255 If set to a bytecode cache object, this object will provide a
256 cache for the internal Jinja bytecode so that templates don't
257 have to be parsed if they were not changed.
259 See :ref:`bytecode-cache` for more information.
261 `enable_async`
262 If set to true this enables async template execution which
263 allows using async functions and generators.
264 """
266 #: if this environment is sandboxed. Modifying this variable won't make
267 #: the environment sandboxed though. For a real sandboxed environment
268 #: have a look at jinja2.sandbox. This flag alone controls the code
269 #: generation by the compiler.
270 sandboxed = False
272 #: True if the environment is just an overlay
273 overlayed = False
275 #: the environment this environment is linked to if it is an overlay
276 linked_to: t.Optional["Environment"] = None
278 #: shared environments have this set to `True`. A shared environment
279 #: must not be modified
280 shared = False
282 #: the class that is used for code generation. See
283 #: :class:`~jinja2.compiler.CodeGenerator` for more information.
284 code_generator_class: t.Type["CodeGenerator"] = CodeGenerator
286 concat = "".join
288 #: the context class that is used for templates. See
289 #: :class:`~jinja2.runtime.Context` for more information.
290 context_class: t.Type[Context] = Context
292 template_class: t.Type["Template"]
294 def __init__(
295 self,
296 block_start_string: str = BLOCK_START_STRING,
297 block_end_string: str = BLOCK_END_STRING,
298 variable_start_string: str = VARIABLE_START_STRING,
299 variable_end_string: str = VARIABLE_END_STRING,
300 comment_start_string: str = COMMENT_START_STRING,
301 comment_end_string: str = COMMENT_END_STRING,
302 line_statement_prefix: t.Optional[str] = LINE_STATEMENT_PREFIX,
303 line_comment_prefix: t.Optional[str] = LINE_COMMENT_PREFIX,
304 trim_blocks: bool = TRIM_BLOCKS,
305 lstrip_blocks: bool = LSTRIP_BLOCKS,
306 newline_sequence: "te.Literal['\\n', '\\r\\n', '\\r']" = NEWLINE_SEQUENCE,
307 keep_trailing_newline: bool = KEEP_TRAILING_NEWLINE,
308 extensions: t.Sequence[t.Union[str, t.Type["Extension"]]] = (),
309 optimized: bool = True,
310 undefined: t.Type[Undefined] = Undefined,
311 finalize: t.Optional[t.Callable[..., t.Any]] = None,
312 autoescape: t.Union[bool, t.Callable[[t.Optional[str]], bool]] = False,
313 loader: t.Optional["BaseLoader"] = None,
314 cache_size: int = 400,
315 auto_reload: bool = True,
316 bytecode_cache: t.Optional["BytecodeCache"] = None,
317 enable_async: bool = False,
318 ):
319 # !!Important notice!!
320 # The constructor accepts quite a few arguments that should be
321 # passed by keyword rather than position. However it's important to
322 # not change the order of arguments because it's used at least
323 # internally in those cases:
324 # - spontaneous environments (i18n extension and Template)
325 # - unittests
326 # If parameter changes are required only add parameters at the end
327 # and don't change the arguments (or the defaults!) of the arguments
328 # existing already.
330 # lexer / parser information
331 self.block_start_string = block_start_string
332 self.block_end_string = block_end_string
333 self.variable_start_string = variable_start_string
334 self.variable_end_string = variable_end_string
335 self.comment_start_string = comment_start_string
336 self.comment_end_string = comment_end_string
337 self.line_statement_prefix = line_statement_prefix
338 self.line_comment_prefix = line_comment_prefix
339 self.trim_blocks = trim_blocks
340 self.lstrip_blocks = lstrip_blocks
341 self.newline_sequence = newline_sequence
342 self.keep_trailing_newline = keep_trailing_newline
344 # runtime information
345 self.undefined: t.Type[Undefined] = undefined
346 self.optimized = optimized
347 self.finalize = finalize
348 self.autoescape = autoescape
350 # defaults
351 self.filters = DEFAULT_FILTERS.copy()
352 self.tests = DEFAULT_TESTS.copy()
353 self.globals = DEFAULT_NAMESPACE.copy()
355 # set the loader provided
356 self.loader = loader
357 self.cache = create_cache(cache_size)
358 self.bytecode_cache = bytecode_cache
359 self.auto_reload = auto_reload
361 # configurable policies
362 self.policies = DEFAULT_POLICIES.copy()
364 # load extensions
365 self.extensions = load_extensions(self, extensions)
367 self.is_async = enable_async
368 _environment_config_check(self)
370 def add_extension(self, extension: t.Union[str, t.Type["Extension"]]) -> None:
371 """Adds an extension after the environment was created.
373 .. versionadded:: 2.5
374 """
375 self.extensions.update(load_extensions(self, [extension]))
377 def extend(self, **attributes: t.Any) -> None:
378 """Add the items to the instance of the environment if they do not exist
379 yet. This is used by :ref:`extensions <writing-extensions>` to register
380 callbacks and configuration values without breaking inheritance.
381 """
382 for key, value in attributes.items():
383 if not hasattr(self, key):
384 setattr(self, key, value)
386 def overlay(
387 self,
388 block_start_string: str = missing,
389 block_end_string: str = missing,
390 variable_start_string: str = missing,
391 variable_end_string: str = missing,
392 comment_start_string: str = missing,
393 comment_end_string: str = missing,
394 line_statement_prefix: t.Optional[str] = missing,
395 line_comment_prefix: t.Optional[str] = missing,
396 trim_blocks: bool = missing,
397 lstrip_blocks: bool = missing,
398 newline_sequence: "te.Literal['\\n', '\\r\\n', '\\r']" = missing,
399 keep_trailing_newline: bool = missing,
400 extensions: t.Sequence[t.Union[str, t.Type["Extension"]]] = missing,
401 optimized: bool = missing,
402 undefined: t.Type[Undefined] = missing,
403 finalize: t.Optional[t.Callable[..., t.Any]] = missing,
404 autoescape: t.Union[bool, t.Callable[[t.Optional[str]], bool]] = missing,
405 loader: t.Optional["BaseLoader"] = missing,
406 cache_size: int = missing,
407 auto_reload: bool = missing,
408 bytecode_cache: t.Optional["BytecodeCache"] = missing,
409 enable_async: bool = missing,
410 ) -> "te.Self":
411 """Create a new overlay environment that shares all the data with the
412 current environment except for cache and the overridden attributes.
413 Extensions cannot be removed for an overlayed environment. An overlayed
414 environment automatically gets all the extensions of the environment it
415 is linked to plus optional extra extensions.
417 Creating overlays should happen after the initial environment was set
418 up completely. Not all attributes are truly linked, some are just
419 copied over so modifications on the original environment may not shine
420 through.
422 .. versionchanged:: 3.1.5
423 ``enable_async`` is applied correctly.
425 .. versionchanged:: 3.1.2
426 Added the ``newline_sequence``, ``keep_trailing_newline``,
427 and ``enable_async`` parameters to match ``__init__``.
428 """
429 args = dict(locals())
430 del args["self"], args["cache_size"], args["extensions"], args["enable_async"]
432 rv = object.__new__(self.__class__)
433 rv.__dict__.update(self.__dict__)
434 rv.overlayed = True
435 rv.linked_to = self
437 for key, value in args.items():
438 if value is not missing:
439 setattr(rv, key, value)
441 if cache_size is not missing:
442 rv.cache = create_cache(cache_size)
443 else:
444 rv.cache = copy_cache(self.cache)
446 rv.extensions = {}
447 for key, value in self.extensions.items():
448 rv.extensions[key] = value.bind(rv)
449 if extensions is not missing:
450 rv.extensions.update(load_extensions(rv, extensions))
452 if enable_async is not missing:
453 rv.is_async = enable_async
455 return _environment_config_check(rv)
457 @property
458 def lexer(self) -> Lexer:
459 """The lexer for this environment."""
460 return get_lexer(self)
462 def iter_extensions(self) -> t.Iterator["Extension"]:
463 """Iterates over the extensions by priority."""
464 return iter(sorted(self.extensions.values(), key=lambda x: x.priority))
466 def getitem(
467 self, obj: t.Any, argument: t.Union[str, t.Any]
468 ) -> t.Union[t.Any, Undefined]:
469 """Get an item or attribute of an object but prefer the item."""
470 try:
471 return obj[argument]
472 except (AttributeError, TypeError, LookupError):
473 if isinstance(argument, str):
474 try:
475 attr = str(argument)
476 except Exception:
477 pass
478 else:
479 try:
480 return getattr(obj, attr)
481 except AttributeError:
482 pass
483 return self.undefined(obj=obj, name=argument)
485 def getattr(self, obj: t.Any, attribute: str) -> t.Any:
486 """Get an item or attribute of an object but prefer the attribute.
487 Unlike :meth:`getitem` the attribute *must* be a string.
488 """
489 try:
490 return getattr(obj, attribute)
491 except AttributeError:
492 pass
493 try:
494 return obj[attribute]
495 except (TypeError, LookupError, AttributeError):
496 return self.undefined(obj=obj, name=attribute)
498 def _filter_test_common(
499 self,
500 name: t.Union[str, Undefined],
501 value: t.Any,
502 args: t.Optional[t.Sequence[t.Any]],
503 kwargs: t.Optional[t.Mapping[str, t.Any]],
504 context: t.Optional[Context],
505 eval_ctx: t.Optional[EvalContext],
506 is_filter: bool,
507 ) -> t.Any:
508 if is_filter:
509 env_map = self.filters
510 type_name = "filter"
511 else:
512 env_map = self.tests
513 type_name = "test"
515 func = env_map.get(name) # type: ignore
517 if func is None:
518 msg = f"No {type_name} named {name!r}."
520 if isinstance(name, Undefined):
521 try:
522 name._fail_with_undefined_error()
523 except Exception as e:
524 msg = f"{msg} ({e}; did you forget to quote the callable name?)"
526 raise TemplateRuntimeError(msg)
528 args = [value, *(args if args is not None else ())]
529 kwargs = kwargs if kwargs is not None else {}
530 pass_arg = _PassArg.from_obj(func)
532 if pass_arg is _PassArg.context:
533 if context is None:
534 raise TemplateRuntimeError(
535 f"Attempted to invoke a context {type_name} without context."
536 )
538 args.insert(0, context)
539 elif pass_arg is _PassArg.eval_context:
540 if eval_ctx is None:
541 if context is not None:
542 eval_ctx = context.eval_ctx
543 else:
544 eval_ctx = EvalContext(self)
546 args.insert(0, eval_ctx)
547 elif pass_arg is _PassArg.environment:
548 args.insert(0, self)
550 return func(*args, **kwargs)
552 def call_filter(
553 self,
554 name: str,
555 value: t.Any,
556 args: t.Optional[t.Sequence[t.Any]] = None,
557 kwargs: t.Optional[t.Mapping[str, t.Any]] = None,
558 context: t.Optional[Context] = None,
559 eval_ctx: t.Optional[EvalContext] = None,
560 ) -> t.Any:
561 """Invoke a filter on a value the same way the compiler does.
563 This might return a coroutine if the filter is running from an
564 environment in async mode and the filter supports async
565 execution. It's your responsibility to await this if needed.
567 .. versionadded:: 2.7
568 """
569 return self._filter_test_common(
570 name, value, args, kwargs, context, eval_ctx, True
571 )
573 def call_test(
574 self,
575 name: str,
576 value: t.Any,
577 args: t.Optional[t.Sequence[t.Any]] = None,
578 kwargs: t.Optional[t.Mapping[str, t.Any]] = None,
579 context: t.Optional[Context] = None,
580 eval_ctx: t.Optional[EvalContext] = None,
581 ) -> t.Any:
582 """Invoke a test on a value the same way the compiler does.
584 This might return a coroutine if the test is running from an
585 environment in async mode and the test supports async execution.
586 It's your responsibility to await this if needed.
588 .. versionchanged:: 3.0
589 Tests support ``@pass_context``, etc. decorators. Added
590 the ``context`` and ``eval_ctx`` parameters.
592 .. versionadded:: 2.7
593 """
594 return self._filter_test_common(
595 name, value, args, kwargs, context, eval_ctx, False
596 )
598 @internalcode
599 def parse(
600 self,
601 source: str,
602 name: t.Optional[str] = None,
603 filename: t.Optional[str] = None,
604 ) -> nodes.Template:
605 """Parse the sourcecode and return the abstract syntax tree. This
606 tree of nodes is used by the compiler to convert the template into
607 executable source- or bytecode. This is useful for debugging or to
608 extract information from templates.
610 If you are :ref:`developing Jinja extensions <writing-extensions>`
611 this gives you a good overview of the node tree generated.
612 """
613 try:
614 return self._parse(source, name, filename)
615 except TemplateSyntaxError:
616 self.handle_exception(source=source)
618 def _parse(
619 self, source: str, name: t.Optional[str], filename: t.Optional[str]
620 ) -> nodes.Template:
621 """Internal parsing function used by `parse` and `compile`."""
622 return Parser(self, source, name, filename).parse()
624 def lex(
625 self,
626 source: str,
627 name: t.Optional[str] = None,
628 filename: t.Optional[str] = None,
629 ) -> t.Iterator[t.Tuple[int, str, str]]:
630 """Lex the given sourcecode and return a generator that yields
631 tokens as tuples in the form ``(lineno, token_type, value)``.
632 This can be useful for :ref:`extension development <writing-extensions>`
633 and debugging templates.
635 This does not perform preprocessing. If you want the preprocessing
636 of the extensions to be applied you have to filter source through
637 the :meth:`preprocess` method.
638 """
639 source = str(source)
640 try:
641 return self.lexer.tokeniter(source, name, filename)
642 except TemplateSyntaxError:
643 self.handle_exception(source=source)
645 def preprocess(
646 self,
647 source: str,
648 name: t.Optional[str] = None,
649 filename: t.Optional[str] = None,
650 ) -> str:
651 """Preprocesses the source with all extensions. This is automatically
652 called for all parsing and compiling methods but *not* for :meth:`lex`
653 because there you usually only want the actual source tokenized.
654 """
655 return reduce(
656 lambda s, e: e.preprocess(s, name, filename),
657 self.iter_extensions(),
658 str(source),
659 )
661 def _tokenize(
662 self,
663 source: str,
664 name: t.Optional[str],
665 filename: t.Optional[str] = None,
666 state: t.Optional[str] = None,
667 ) -> TokenStream:
668 """Called by the parser to do the preprocessing and filtering
669 for all the extensions. Returns a :class:`~jinja2.lexer.TokenStream`.
670 """
671 source = self.preprocess(source, name, filename)
672 stream = self.lexer.tokenize(source, name, filename, state)
674 for ext in self.iter_extensions():
675 stream = ext.filter_stream(stream) # type: ignore
677 if not isinstance(stream, TokenStream):
678 stream = TokenStream(stream, name, filename)
680 return stream
682 def _generate(
683 self,
684 source: nodes.Template,
685 name: t.Optional[str],
686 filename: t.Optional[str],
687 defer_init: bool = False,
688 ) -> str:
689 """Internal hook that can be overridden to hook a different generate
690 method in.
692 .. versionadded:: 2.5
693 """
694 return generate( # type: ignore
695 source,
696 self,
697 name,
698 filename,
699 defer_init=defer_init,
700 optimized=self.optimized,
701 )
703 def _compile(self, source: str, filename: str) -> CodeType:
704 """Internal hook that can be overridden to hook a different compile
705 method in.
707 .. versionadded:: 2.5
708 """
709 return compile(source, filename, "exec")
711 @typing.overload
712 def compile(
713 self,
714 source: t.Union[str, nodes.Template],
715 name: t.Optional[str] = None,
716 filename: t.Optional[str] = None,
717 raw: "te.Literal[False]" = False,
718 defer_init: bool = False,
719 ) -> CodeType: ...
721 @typing.overload
722 def compile(
723 self,
724 source: t.Union[str, nodes.Template],
725 name: t.Optional[str] = None,
726 filename: t.Optional[str] = None,
727 raw: "te.Literal[True]" = ...,
728 defer_init: bool = False,
729 ) -> str: ...
731 @internalcode
732 def compile(
733 self,
734 source: t.Union[str, nodes.Template],
735 name: t.Optional[str] = None,
736 filename: t.Optional[str] = None,
737 raw: bool = False,
738 defer_init: bool = False,
739 ) -> t.Union[str, CodeType]:
740 """Compile a node or template source code. The `name` parameter is
741 the load name of the template after it was joined using
742 :meth:`join_path` if necessary, not the filename on the file system.
743 the `filename` parameter is the estimated filename of the template on
744 the file system. If the template came from a database or memory this
745 can be omitted.
747 The return value of this method is a python code object. If the `raw`
748 parameter is `True` the return value will be a string with python
749 code equivalent to the bytecode returned otherwise. This method is
750 mainly used internally.
752 `defer_init` is use internally to aid the module code generator. This
753 causes the generated code to be able to import without the global
754 environment variable to be set.
756 .. versionadded:: 2.4
757 `defer_init` parameter added.
758 """
759 source_hint = None
760 try:
761 if isinstance(source, str):
762 source_hint = source
763 source = self._parse(source, name, filename)
764 source = self._generate(source, name, filename, defer_init=defer_init)
765 if raw:
766 return source
767 if filename is None:
768 filename = "<template>"
769 return self._compile(source, filename)
770 except TemplateSyntaxError:
771 self.handle_exception(source=source_hint)
773 def compile_expression(
774 self, source: str, undefined_to_none: bool = True
775 ) -> "TemplateExpression":
776 """A handy helper method that returns a callable that accepts keyword
777 arguments that appear as variables in the expression. If called it
778 returns the result of the expression.
780 This is useful if applications want to use the same rules as Jinja
781 in template "configuration files" or similar situations.
783 Example usage:
785 >>> env = Environment()
786 >>> expr = env.compile_expression('foo == 42')
787 >>> expr(foo=23)
788 False
789 >>> expr(foo=42)
790 True
792 Per default the return value is converted to `None` if the
793 expression returns an undefined value. This can be changed
794 by setting `undefined_to_none` to `False`.
796 >>> env.compile_expression('var')() is None
797 True
798 >>> env.compile_expression('var', undefined_to_none=False)()
799 Undefined
801 .. versionadded:: 2.1
802 """
803 parser = Parser(self, source, state="variable")
804 try:
805 expr = parser.parse_expression()
806 if not parser.stream.eos:
807 raise TemplateSyntaxError(
808 "chunk after expression", parser.stream.current.lineno, None, None
809 )
810 expr.set_environment(self)
811 except TemplateSyntaxError:
812 self.handle_exception(source=source)
814 body = [nodes.Assign(nodes.Name("result", "store"), expr, lineno=1)]
815 template = self.from_string(nodes.Template(body, lineno=1))
816 return TemplateExpression(template, undefined_to_none)
818 def compile_templates(
819 self,
820 target: t.Union[str, "os.PathLike[str]"],
821 extensions: t.Optional[t.Collection[str]] = None,
822 filter_func: t.Optional[t.Callable[[str], bool]] = None,
823 zip: t.Optional[str] = "deflated",
824 log_function: t.Optional[t.Callable[[str], None]] = None,
825 ignore_errors: bool = True,
826 ) -> None:
827 """Finds all the templates the loader can find, compiles them
828 and stores them in `target`. If `zip` is `None`, instead of in a
829 zipfile, the templates will be stored in a directory.
830 By default a deflate zip algorithm is used. To switch to
831 the stored algorithm, `zip` can be set to ``'stored'``.
833 `extensions` and `filter_func` are passed to :meth:`list_templates`.
834 Each template returned will be compiled to the target folder or
835 zipfile.
837 By default template compilation errors are ignored. In case a
838 log function is provided, errors are logged. If you want template
839 syntax errors to abort the compilation you can set `ignore_errors`
840 to `False` and you will get an exception on syntax errors.
842 .. versionadded:: 2.4
843 """
844 from .loaders import ModuleLoader
846 if log_function is None:
848 def log_function(x: str) -> None:
849 pass
851 assert log_function is not None
852 assert self.loader is not None, "No loader configured."
854 def write_file(filename: str, data: str) -> None:
855 if zip:
856 info = ZipInfo(filename)
857 info.external_attr = 0o755 << 16
858 zip_file.writestr(info, data)
859 else:
860 with open(os.path.join(target, filename), "wb") as f:
861 f.write(data.encode("utf8"))
863 if zip is not None:
864 from zipfile import ZIP_DEFLATED
865 from zipfile import ZIP_STORED
866 from zipfile import ZipFile
867 from zipfile import ZipInfo
869 zip_file = ZipFile(
870 target, "w", dict(deflated=ZIP_DEFLATED, stored=ZIP_STORED)[zip]
871 )
872 log_function(f"Compiling into Zip archive {target!r}")
873 else:
874 if not os.path.isdir(target):
875 os.makedirs(target)
876 log_function(f"Compiling into folder {target!r}")
878 try:
879 for name in self.list_templates(extensions, filter_func):
880 source, filename, _ = self.loader.get_source(self, name)
881 try:
882 code = self.compile(source, name, filename, True, True)
883 except TemplateSyntaxError as e:
884 if not ignore_errors:
885 raise
886 log_function(f'Could not compile "{name}": {e}')
887 continue
889 filename = ModuleLoader.get_module_filename(name)
891 write_file(filename, code)
892 log_function(f'Compiled "{name}" as {filename}')
893 finally:
894 if zip:
895 zip_file.close()
897 log_function("Finished compiling templates")
899 def list_templates(
900 self,
901 extensions: t.Optional[t.Collection[str]] = None,
902 filter_func: t.Optional[t.Callable[[str], bool]] = None,
903 ) -> t.List[str]:
904 """Returns a list of templates for this environment. This requires
905 that the loader supports the loader's
906 :meth:`~BaseLoader.list_templates` method.
908 If there are other files in the template folder besides the
909 actual templates, the returned list can be filtered. There are two
910 ways: either `extensions` is set to a list of file extensions for
911 templates, or a `filter_func` can be provided which is a callable that
912 is passed a template name and should return `True` if it should end up
913 in the result list.
915 If the loader does not support that, a :exc:`TypeError` is raised.
917 .. versionadded:: 2.4
918 """
919 assert self.loader is not None, "No loader configured."
920 names = self.loader.list_templates()
922 if extensions is not None:
923 if filter_func is not None:
924 raise TypeError(
925 "either extensions or filter_func can be passed, but not both"
926 )
928 def filter_func(x: str) -> bool:
929 return "." in x and x.rsplit(".", 1)[1] in extensions
931 if filter_func is not None:
932 names = [name for name in names if filter_func(name)]
934 return names
936 def handle_exception(self, source: t.Optional[str] = None) -> "te.NoReturn":
937 """Exception handling helper. This is used internally to either raise
938 rewritten exceptions or return a rendered traceback for the template.
939 """
940 from .debug import rewrite_traceback_stack
942 raise rewrite_traceback_stack(source=source)
944 def join_path(self, template: str, parent: str) -> str:
945 """Join a template with the parent. By default all the lookups are
946 relative to the loader root so this method returns the `template`
947 parameter unchanged, but if the paths should be relative to the
948 parent template, this function can be used to calculate the real
949 template name.
951 Subclasses may override this method and implement template path
952 joining here.
953 """
954 return template
956 @internalcode
957 def _load_template(
958 self, name: str, globals: t.Optional[t.MutableMapping[str, t.Any]]
959 ) -> "Template":
960 if self.loader is None:
961 raise TypeError("no loader for this environment specified")
962 cache_key = (weakref.ref(self.loader), name)
963 if self.cache is not None:
964 template = self.cache.get(cache_key)
965 if template is not None and (
966 not self.auto_reload or template.is_up_to_date
967 ):
968 # template.globals is a ChainMap, modifying it will only
969 # affect the template, not the environment globals.
970 if globals:
971 template.globals.update(globals)
973 return template
975 template = self.loader.load(self, name, self.make_globals(globals))
977 if self.cache is not None:
978 self.cache[cache_key] = template
979 return template
981 @internalcode
982 def get_template(
983 self,
984 name: t.Union[str, "Template"],
985 parent: t.Optional[str] = None,
986 globals: t.Optional[t.MutableMapping[str, t.Any]] = None,
987 ) -> "Template":
988 """Load a template by name with :attr:`loader` and return a
989 :class:`Template`. If the template does not exist a
990 :exc:`TemplateNotFound` exception is raised.
992 :param name: Name of the template to load. When loading
993 templates from the filesystem, "/" is used as the path
994 separator, even on Windows.
995 :param parent: The name of the parent template importing this
996 template. :meth:`join_path` can be used to implement name
997 transformations with this.
998 :param globals: Extend the environment :attr:`globals` with
999 these extra variables available for all renders of this
1000 template. If the template has already been loaded and
1001 cached, its globals are updated with any new items.
1003 .. versionchanged:: 3.0
1004 If a template is loaded from cache, ``globals`` will update
1005 the template's globals instead of ignoring the new values.
1007 .. versionchanged:: 2.4
1008 If ``name`` is a :class:`Template` object it is returned
1009 unchanged.
1010 """
1011 if isinstance(name, Template):
1012 return name
1013 if parent is not None:
1014 name = self.join_path(name, parent)
1016 return self._load_template(name, globals)
1018 @internalcode
1019 def select_template(
1020 self,
1021 names: t.Iterable[t.Union[str, "Template"]],
1022 parent: t.Optional[str] = None,
1023 globals: t.Optional[t.MutableMapping[str, t.Any]] = None,
1024 ) -> "Template":
1025 """Like :meth:`get_template`, but tries loading multiple names.
1026 If none of the names can be loaded a :exc:`TemplatesNotFound`
1027 exception is raised.
1029 :param names: List of template names to try loading in order.
1030 :param parent: The name of the parent template importing this
1031 template. :meth:`join_path` can be used to implement name
1032 transformations with this.
1033 :param globals: Extend the environment :attr:`globals` with
1034 these extra variables available for all renders of this
1035 template. If the template has already been loaded and
1036 cached, its globals are updated with any new items.
1038 .. versionchanged:: 3.0
1039 If a template is loaded from cache, ``globals`` will update
1040 the template's globals instead of ignoring the new values.
1042 .. versionchanged:: 2.11
1043 If ``names`` is :class:`Undefined`, an :exc:`UndefinedError`
1044 is raised instead. If no templates were found and ``names``
1045 contains :class:`Undefined`, the message is more helpful.
1047 .. versionchanged:: 2.4
1048 If ``names`` contains a :class:`Template` object it is
1049 returned unchanged.
1051 .. versionadded:: 2.3
1052 """
1053 if isinstance(names, Undefined):
1054 names._fail_with_undefined_error()
1056 if not names:
1057 raise TemplatesNotFound(
1058 message="Tried to select from an empty list of templates."
1059 )
1061 for name in names:
1062 if isinstance(name, Template):
1063 return name
1064 if parent is not None:
1065 name = self.join_path(name, parent)
1066 try:
1067 return self._load_template(name, globals)
1068 except (TemplateNotFound, UndefinedError):
1069 pass
1070 raise TemplatesNotFound(names) # type: ignore
1072 @internalcode
1073 def get_or_select_template(
1074 self,
1075 template_name_or_list: t.Union[
1076 str, "Template", t.List[t.Union[str, "Template"]]
1077 ],
1078 parent: t.Optional[str] = None,
1079 globals: t.Optional[t.MutableMapping[str, t.Any]] = None,
1080 ) -> "Template":
1081 """Use :meth:`select_template` if an iterable of template names
1082 is given, or :meth:`get_template` if one name is given.
1084 .. versionadded:: 2.3
1085 """
1086 if isinstance(template_name_or_list, (str, Undefined)):
1087 return self.get_template(template_name_or_list, parent, globals)
1088 elif isinstance(template_name_or_list, Template):
1089 return template_name_or_list
1090 return self.select_template(template_name_or_list, parent, globals)
1092 def from_string(
1093 self,
1094 source: t.Union[str, nodes.Template],
1095 globals: t.Optional[t.MutableMapping[str, t.Any]] = None,
1096 template_class: t.Optional[t.Type["Template"]] = None,
1097 ) -> "Template":
1098 """Load a template from a source string without using
1099 :attr:`loader`.
1101 :param source: Jinja source to compile into a template.
1102 :param globals: Extend the environment :attr:`globals` with
1103 these extra variables available for all renders of this
1104 template. If the template has already been loaded and
1105 cached, its globals are updated with any new items.
1106 :param template_class: Return an instance of this
1107 :class:`Template` class.
1108 """
1109 gs = self.make_globals(globals)
1110 cls = template_class or self.template_class
1111 return cls.from_code(self, self.compile(source), gs, None)
1113 def make_globals(
1114 self, d: t.Optional[t.MutableMapping[str, t.Any]]
1115 ) -> t.MutableMapping[str, t.Any]:
1116 """Make the globals map for a template. Any given template
1117 globals overlay the environment :attr:`globals`.
1119 Returns a :class:`collections.ChainMap`. This allows any changes
1120 to a template's globals to only affect that template, while
1121 changes to the environment's globals are still reflected.
1122 However, avoid modifying any globals after a template is loaded.
1124 :param d: Dict of template-specific globals.
1126 .. versionchanged:: 3.0
1127 Use :class:`collections.ChainMap` to always prevent mutating
1128 environment globals.
1129 """
1130 if d is None:
1131 d = {}
1133 return ChainMap(d, self.globals)
1136class Template:
1137 """A compiled template that can be rendered.
1139 Use the methods on :class:`Environment` to create or load templates.
1140 The environment is used to configure how templates are compiled and
1141 behave.
1143 It is also possible to create a template object directly. This is
1144 not usually recommended. The constructor takes most of the same
1145 arguments as :class:`Environment`. All templates created with the
1146 same environment arguments share the same ephemeral ``Environment``
1147 instance behind the scenes.
1149 A template object should be considered immutable. Modifications on
1150 the object are not supported.
1151 """
1153 #: Type of environment to create when creating a template directly
1154 #: rather than through an existing environment.
1155 environment_class: t.Type[Environment] = Environment
1157 environment: Environment
1158 globals: t.MutableMapping[str, t.Any]
1159 name: t.Optional[str]
1160 filename: t.Optional[str]
1161 blocks: t.Dict[str, t.Callable[[Context], t.Iterator[str]]]
1162 root_render_func: t.Callable[[Context], t.Iterator[str]]
1163 _module: t.Optional["TemplateModule"]
1164 _debug_info: str
1165 _uptodate: t.Optional[t.Callable[[], bool]]
1167 def __new__(
1168 cls,
1169 source: t.Union[str, nodes.Template],
1170 block_start_string: str = BLOCK_START_STRING,
1171 block_end_string: str = BLOCK_END_STRING,
1172 variable_start_string: str = VARIABLE_START_STRING,
1173 variable_end_string: str = VARIABLE_END_STRING,
1174 comment_start_string: str = COMMENT_START_STRING,
1175 comment_end_string: str = COMMENT_END_STRING,
1176 line_statement_prefix: t.Optional[str] = LINE_STATEMENT_PREFIX,
1177 line_comment_prefix: t.Optional[str] = LINE_COMMENT_PREFIX,
1178 trim_blocks: bool = TRIM_BLOCKS,
1179 lstrip_blocks: bool = LSTRIP_BLOCKS,
1180 newline_sequence: "te.Literal['\\n', '\\r\\n', '\\r']" = NEWLINE_SEQUENCE,
1181 keep_trailing_newline: bool = KEEP_TRAILING_NEWLINE,
1182 extensions: t.Sequence[t.Union[str, t.Type["Extension"]]] = (),
1183 optimized: bool = True,
1184 undefined: t.Type[Undefined] = Undefined,
1185 finalize: t.Optional[t.Callable[..., t.Any]] = None,
1186 autoescape: t.Union[bool, t.Callable[[t.Optional[str]], bool]] = False,
1187 enable_async: bool = False,
1188 ) -> t.Any: # it returns a `Template`, but this breaks the sphinx build...
1189 env = get_spontaneous_environment(
1190 cls.environment_class, # type: ignore
1191 block_start_string,
1192 block_end_string,
1193 variable_start_string,
1194 variable_end_string,
1195 comment_start_string,
1196 comment_end_string,
1197 line_statement_prefix,
1198 line_comment_prefix,
1199 trim_blocks,
1200 lstrip_blocks,
1201 newline_sequence,
1202 keep_trailing_newline,
1203 frozenset(extensions),
1204 optimized,
1205 undefined, # type: ignore
1206 finalize,
1207 autoescape,
1208 None,
1209 0,
1210 False,
1211 None,
1212 enable_async,
1213 )
1214 return env.from_string(source, template_class=cls)
1216 @classmethod
1217 def from_code(
1218 cls,
1219 environment: Environment,
1220 code: CodeType,
1221 globals: t.MutableMapping[str, t.Any],
1222 uptodate: t.Optional[t.Callable[[], bool]] = None,
1223 ) -> "Template":
1224 """Creates a template object from compiled code and the globals. This
1225 is used by the loaders and environment to create a template object.
1226 """
1227 namespace = {"environment": environment, "__file__": code.co_filename}
1228 exec(code, namespace)
1229 rv = cls._from_namespace(environment, namespace, globals)
1230 rv._uptodate = uptodate
1231 return rv
1233 @classmethod
1234 def from_module_dict(
1235 cls,
1236 environment: Environment,
1237 module_dict: t.MutableMapping[str, t.Any],
1238 globals: t.MutableMapping[str, t.Any],
1239 ) -> "Template":
1240 """Creates a template object from a module. This is used by the
1241 module loader to create a template object.
1243 .. versionadded:: 2.4
1244 """
1245 return cls._from_namespace(environment, module_dict, globals)
1247 @classmethod
1248 def _from_namespace(
1249 cls,
1250 environment: Environment,
1251 namespace: t.MutableMapping[str, t.Any],
1252 globals: t.MutableMapping[str, t.Any],
1253 ) -> "Template":
1254 t: Template = object.__new__(cls)
1255 t.environment = environment
1256 t.globals = globals
1257 t.name = namespace["name"]
1258 t.filename = namespace["__file__"]
1259 t.blocks = namespace["blocks"]
1261 # render function and module
1262 t.root_render_func = namespace["root"]
1263 t._module = None
1265 # debug and loader helpers
1266 t._debug_info = namespace["debug_info"]
1267 t._uptodate = None
1269 # store the reference
1270 namespace["environment"] = environment
1271 namespace["__jinja_template__"] = t
1273 return t
1275 def render(self, *args: t.Any, **kwargs: t.Any) -> str:
1276 """This method accepts the same arguments as the `dict` constructor:
1277 A dict, a dict subclass or some keyword arguments. If no arguments
1278 are given the context will be empty. These two calls do the same::
1280 template.render(knights='that say nih')
1281 template.render({'knights': 'that say nih'})
1283 This will return the rendered template as a string.
1284 """
1285 if self.environment.is_async:
1286 import asyncio
1288 return asyncio.run(self.render_async(*args, **kwargs))
1290 ctx = self.new_context(dict(*args, **kwargs))
1292 try:
1293 return self.environment.concat(self.root_render_func(ctx)) # type: ignore
1294 except Exception:
1295 self.environment.handle_exception()
1297 async def render_async(self, *args: t.Any, **kwargs: t.Any) -> str:
1298 """This works similar to :meth:`render` but returns a coroutine
1299 that when awaited returns the entire rendered template string. This
1300 requires the async feature to be enabled.
1302 Example usage::
1304 await template.render_async(knights='that say nih; asynchronously')
1305 """
1306 if not self.environment.is_async:
1307 raise RuntimeError(
1308 "The environment was not created with async mode enabled."
1309 )
1311 ctx = self.new_context(dict(*args, **kwargs))
1313 try:
1314 return self.environment.concat( # type: ignore
1315 [n async for n in self.root_render_func(ctx)] # type: ignore
1316 )
1317 except Exception:
1318 return self.environment.handle_exception()
1320 def stream(self, *args: t.Any, **kwargs: t.Any) -> "TemplateStream":
1321 """Works exactly like :meth:`generate` but returns a
1322 :class:`TemplateStream`.
1323 """
1324 return TemplateStream(self.generate(*args, **kwargs))
1326 def generate(self, *args: t.Any, **kwargs: t.Any) -> t.Iterator[str]:
1327 """For very large templates it can be useful to not render the whole
1328 template at once but evaluate each statement after another and yield
1329 piece for piece. This method basically does exactly that and returns
1330 a generator that yields one item after another as strings.
1332 It accepts the same arguments as :meth:`render`.
1333 """
1334 if self.environment.is_async:
1335 import asyncio
1337 async def to_list() -> t.List[str]:
1338 return [x async for x in self.generate_async(*args, **kwargs)]
1340 yield from asyncio.run(to_list())
1341 return
1343 ctx = self.new_context(dict(*args, **kwargs))
1345 try:
1346 yield from self.root_render_func(ctx)
1347 except Exception:
1348 yield self.environment.handle_exception()
1350 async def generate_async(
1351 self, *args: t.Any, **kwargs: t.Any
1352 ) -> t.AsyncGenerator[str, object]:
1353 """An async version of :meth:`generate`. Works very similarly but
1354 returns an async iterator instead.
1355 """
1356 if not self.environment.is_async:
1357 raise RuntimeError(
1358 "The environment was not created with async mode enabled."
1359 )
1361 ctx = self.new_context(dict(*args, **kwargs))
1363 try:
1364 agen = self.root_render_func(ctx)
1365 try:
1366 async for event in agen: # type: ignore
1367 yield event
1368 finally:
1369 # we can't use async with aclosing(...) because that's only
1370 # in 3.10+
1371 await agen.aclose() # type: ignore
1372 except Exception:
1373 yield self.environment.handle_exception()
1375 def new_context(
1376 self,
1377 vars: t.Optional[t.Dict[str, t.Any]] = None,
1378 shared: bool = False,
1379 locals: t.Optional[t.Mapping[str, t.Any]] = None,
1380 ) -> Context:
1381 """Create a new :class:`Context` for this template. The vars
1382 provided will be passed to the template. Per default the globals
1383 are added to the context. If shared is set to `True` the data
1384 is passed as is to the context without adding the globals.
1386 `locals` can be a dict of local variables for internal usage.
1387 """
1388 return new_context(
1389 self.environment, self.name, self.blocks, vars, shared, self.globals, locals
1390 )
1392 def make_module(
1393 self,
1394 vars: t.Optional[t.Dict[str, t.Any]] = None,
1395 shared: bool = False,
1396 locals: t.Optional[t.Mapping[str, t.Any]] = None,
1397 ) -> "TemplateModule":
1398 """This method works like the :attr:`module` attribute when called
1399 without arguments but it will evaluate the template on every call
1400 rather than caching it. It's also possible to provide
1401 a dict which is then used as context. The arguments are the same
1402 as for the :meth:`new_context` method.
1403 """
1404 ctx = self.new_context(vars, shared, locals)
1405 return TemplateModule(self, ctx)
1407 async def make_module_async(
1408 self,
1409 vars: t.Optional[t.Dict[str, t.Any]] = None,
1410 shared: bool = False,
1411 locals: t.Optional[t.Mapping[str, t.Any]] = None,
1412 ) -> "TemplateModule":
1413 """As template module creation can invoke template code for
1414 asynchronous executions this method must be used instead of the
1415 normal :meth:`make_module` one. Likewise the module attribute
1416 becomes unavailable in async mode.
1417 """
1418 ctx = self.new_context(vars, shared, locals)
1419 return TemplateModule(
1420 self,
1421 ctx,
1422 [x async for x in self.root_render_func(ctx)], # type: ignore
1423 )
1425 @internalcode
1426 def _get_default_module(self, ctx: t.Optional[Context] = None) -> "TemplateModule":
1427 """If a context is passed in, this means that the template was
1428 imported. Imported templates have access to the current
1429 template's globals by default, but they can only be accessed via
1430 the context during runtime.
1432 If there are new globals, we need to create a new module because
1433 the cached module is already rendered and will not have access
1434 to globals from the current context. This new module is not
1435 cached because the template can be imported elsewhere, and it
1436 should have access to only the current template's globals.
1437 """
1438 if self.environment.is_async:
1439 raise RuntimeError("Module is not available in async mode.")
1441 if ctx is not None:
1442 keys = ctx.globals_keys - self.globals.keys()
1444 if keys:
1445 return self.make_module({k: ctx.parent[k] for k in keys})
1447 if self._module is None:
1448 self._module = self.make_module()
1450 return self._module
1452 async def _get_default_module_async(
1453 self, ctx: t.Optional[Context] = None
1454 ) -> "TemplateModule":
1455 if ctx is not None:
1456 keys = ctx.globals_keys - self.globals.keys()
1458 if keys:
1459 return await self.make_module_async({k: ctx.parent[k] for k in keys})
1461 if self._module is None:
1462 self._module = await self.make_module_async()
1464 return self._module
1466 @property
1467 def module(self) -> "TemplateModule":
1468 """The template as module. This is used for imports in the
1469 template runtime but is also useful if one wants to access
1470 exported template variables from the Python layer:
1472 >>> t = Template('{% macro foo() %}42{% endmacro %}23')
1473 >>> str(t.module)
1474 '23'
1475 >>> t.module.foo() == u'42'
1476 True
1478 This attribute is not available if async mode is enabled.
1479 """
1480 return self._get_default_module()
1482 def get_corresponding_lineno(self, lineno: int) -> int:
1483 """Return the source line number of a line number in the
1484 generated bytecode as they are not in sync.
1485 """
1486 for template_line, code_line in reversed(self.debug_info):
1487 if code_line <= lineno:
1488 return template_line
1489 return 1
1491 @property
1492 def is_up_to_date(self) -> bool:
1493 """If this variable is `False` there is a newer version available."""
1494 if self._uptodate is None:
1495 return True
1496 return self._uptodate()
1498 @property
1499 def debug_info(self) -> t.List[t.Tuple[int, int]]:
1500 """The debug info mapping."""
1501 if self._debug_info:
1502 return [
1503 tuple(map(int, x.split("="))) # type: ignore
1504 for x in self._debug_info.split("&")
1505 ]
1507 return []
1509 def __repr__(self) -> str:
1510 if self.name is None:
1511 name = f"memory:{id(self):x}"
1512 else:
1513 name = repr(self.name)
1514 return f"<{type(self).__name__} {name}>"
1517class TemplateModule:
1518 """Represents an imported template. All the exported names of the
1519 template are available as attributes on this object. Additionally
1520 converting it into a string renders the contents.
1521 """
1523 def __init__(
1524 self,
1525 template: Template,
1526 context: Context,
1527 body_stream: t.Optional[t.Iterable[str]] = None,
1528 ) -> None:
1529 if body_stream is None:
1530 if context.environment.is_async:
1531 raise RuntimeError(
1532 "Async mode requires a body stream to be passed to"
1533 " a template module. Use the async methods of the"
1534 " API you are using."
1535 )
1537 body_stream = list(template.root_render_func(context))
1539 self._body_stream = body_stream
1540 self.__dict__.update(context.get_exported())
1541 self.__name__ = template.name
1543 def __html__(self) -> Markup:
1544 return Markup(concat(self._body_stream))
1546 def __str__(self) -> str:
1547 return concat(self._body_stream)
1549 def __repr__(self) -> str:
1550 if self.__name__ is None:
1551 name = f"memory:{id(self):x}"
1552 else:
1553 name = repr(self.__name__)
1554 return f"<{type(self).__name__} {name}>"
1557class TemplateExpression:
1558 """The :meth:`jinja2.Environment.compile_expression` method returns an
1559 instance of this object. It encapsulates the expression-like access
1560 to the template with an expression it wraps.
1561 """
1563 def __init__(self, template: Template, undefined_to_none: bool) -> None:
1564 self._template = template
1565 self._undefined_to_none = undefined_to_none
1567 def __call__(self, *args: t.Any, **kwargs: t.Any) -> t.Optional[t.Any]:
1568 context = self._template.new_context(dict(*args, **kwargs))
1569 consume(self._template.root_render_func(context))
1570 rv = context.vars["result"]
1571 if self._undefined_to_none and isinstance(rv, Undefined):
1572 rv = None
1573 return rv
1576class TemplateStream:
1577 """A template stream works pretty much like an ordinary python generator
1578 but it can buffer multiple items to reduce the number of total iterations.
1579 Per default the output is unbuffered which means that for every unbuffered
1580 instruction in the template one string is yielded.
1582 If buffering is enabled with a buffer size of 5, five items are combined
1583 into a new string. This is mainly useful if you are streaming
1584 big templates to a client via WSGI which flushes after each iteration.
1585 """
1587 def __init__(self, gen: t.Iterator[str]) -> None:
1588 self._gen = gen
1589 self.disable_buffering()
1591 def dump(
1592 self,
1593 fp: t.Union[str, t.IO[bytes]],
1594 encoding: t.Optional[str] = None,
1595 errors: t.Optional[str] = "strict",
1596 ) -> None:
1597 """Dump the complete stream into a file or file-like object.
1598 Per default strings are written, if you want to encode
1599 before writing specify an `encoding`.
1601 Example usage::
1603 Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
1604 """
1605 close = False
1607 if isinstance(fp, str):
1608 if encoding is None:
1609 encoding = "utf-8"
1611 real_fp: t.IO[bytes] = open(fp, "wb")
1612 close = True
1613 else:
1614 real_fp = fp
1616 try:
1617 if encoding is not None:
1618 iterable = (x.encode(encoding, errors) for x in self) # type: ignore
1619 else:
1620 iterable = self # type: ignore
1622 if hasattr(real_fp, "writelines"):
1623 real_fp.writelines(iterable)
1624 else:
1625 for item in iterable:
1626 real_fp.write(item)
1627 finally:
1628 if close:
1629 real_fp.close()
1631 def disable_buffering(self) -> None:
1632 """Disable the output buffering."""
1633 self._next = partial(next, self._gen)
1634 self.buffered = False
1636 def _buffered_generator(self, size: int) -> t.Iterator[str]:
1637 buf: t.List[str] = []
1638 c_size = 0
1639 push = buf.append
1641 while True:
1642 try:
1643 while c_size < size:
1644 c = next(self._gen)
1645 push(c)
1646 if c:
1647 c_size += 1
1648 except StopIteration:
1649 if not c_size:
1650 return
1651 yield concat(buf)
1652 del buf[:]
1653 c_size = 0
1655 def enable_buffering(self, size: int = 5) -> None:
1656 """Enable buffering. Buffer `size` items before yielding them."""
1657 if size <= 1:
1658 raise ValueError("buffer size too small")
1660 self.buffered = True
1661 self._next = partial(next, self._buffered_generator(size))
1663 def __iter__(self) -> "TemplateStream":
1664 return self
1666 def __next__(self) -> str:
1667 return self._next() # type: ignore
1670# hook in default template class. if anyone reads this comment: ignore that
1671# it's possible to use custom templates ;-)
1672Environment.template_class = Template