jinja2.environment

   1"""Classes for managing templates and their runtime and compile time
   2options.
   3"""
   4
   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
  14
  15from markupsafe import Markup
  16
  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
  56
  57if t.TYPE_CHECKING:
  58    import typing_extensions as te
  59
  60    from .bccache import BytecodeCache
  61    from .ext import Extension
  62    from .loaders import BaseLoader
  63
  64_env_bound = t.TypeVar("_env_bound", bound="Environment")
  65
  66
  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.
  73
  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
  80
  81
  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
  88
  89    if size < 0:
  90        return {}
  91
  92    return LRUCache(size)  # type: ignore
  93
  94
  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
 101
 102    if type(cache) is dict:  # noqa E721
 103        return {}
 104
 105    return LRUCache(cache.capacity)  # type: ignore
 106
 107
 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 = {}
 116
 117    for extension in extensions:
 118        if isinstance(extension, str):
 119            extension = t.cast(t.Type["Extension"], import_string(extension))
 120
 121        result[extension.identifier] = extension(environment)
 122
 123    return result
 124
 125
 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
 142
 143
 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.
 151
 152    Here are the possible initialization parameters:
 153
 154        `block_start_string`
 155            The string marking the beginning of a block.  Defaults to ``'{%'``.
 156
 157        `block_end_string`
 158            The string marking the end of a block.  Defaults to ``'%}'``.
 159
 160        `variable_start_string`
 161            The string marking the beginning of a print statement.
 162            Defaults to ``'{{'``.
 163
 164        `variable_end_string`
 165            The string marking the end of a print statement.  Defaults to
 166            ``'}}'``.
 167
 168        `comment_start_string`
 169            The string marking the beginning of a comment.  Defaults to ``'{#'``.
 170
 171        `comment_end_string`
 172            The string marking the end of a comment.  Defaults to ``'#}'``.
 173
 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`.
 177
 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`.
 181
 182            .. versionadded:: 2.2
 183
 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`.
 187
 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`.
 191
 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.
 197
 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.
 202
 203            .. versionadded:: 2.7
 204
 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>`.
 209
 210        `optimized`
 211            should the optimizer be enabled?  Default is ``True``.
 212
 213        `undefined`
 214            :class:`Undefined` or a subclass of it that is used to represent
 215            undefined values in the template.
 216
 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.
 221
 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.
 229
 230            .. versionchanged:: 2.4
 231               `autoescape` can now be a function
 232
 233        `loader`
 234            The template loader for this environment.
 235
 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.
 242
 243            .. versionchanged:: 2.8
 244               The cache size was increased to 400 from a low 50.
 245
 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.
 253
 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.
 258
 259            See :ref:`bytecode-cache` for more information.
 260
 261        `enable_async`
 262            If set to true this enables async template execution which
 263            allows using async functions and generators.
 264    """
 265
 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
 271
 272    #: True if the environment is just an overlay
 273    overlayed = False
 274
 275    #: the environment this environment is linked to if it is an overlay
 276    linked_to: t.Optional["Environment"] = None
 277
 278    #: shared environments have this set to `True`.  A shared environment
 279    #: must not be modified
 280    shared = False
 281
 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
 285
 286    concat = "".join
 287
 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
 291
 292    template_class: t.Type["Template"]
 293
 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.
 329
 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
 343
 344        # runtime information
 345        self.undefined: t.Type[Undefined] = undefined
 346        self.optimized = optimized
 347        self.finalize = finalize
 348        self.autoescape = autoescape
 349
 350        # defaults
 351        self.filters = DEFAULT_FILTERS.copy()
 352        self.tests = DEFAULT_TESTS.copy()
 353        self.globals = DEFAULT_NAMESPACE.copy()
 354
 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
 360
 361        # configurable policies
 362        self.policies = DEFAULT_POLICIES.copy()
 363
 364        # load extensions
 365        self.extensions = load_extensions(self, extensions)
 366
 367        self.is_async = enable_async
 368        _environment_config_check(self)
 369
 370    def add_extension(self, extension: t.Union[str, t.Type["Extension"]]) -> None:
 371        """Adds an extension after the environment was created.
 372
 373        .. versionadded:: 2.5
 374        """
 375        self.extensions.update(load_extensions(self, [extension]))
 376
 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)
 385
 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.
 416
 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.
 421
 422        .. versionchanged:: 3.1.5
 423            ``enable_async`` is applied correctly.
 424
 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"]
 431
 432        rv = object.__new__(self.__class__)
 433        rv.__dict__.update(self.__dict__)
 434        rv.overlayed = True
 435        rv.linked_to = self
 436
 437        for key, value in args.items():
 438            if value is not missing:
 439                setattr(rv, key, value)
 440
 441        if cache_size is not missing:
 442            rv.cache = create_cache(cache_size)
 443        else:
 444            rv.cache = copy_cache(self.cache)
 445
 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))
 451
 452        if enable_async is not missing:
 453            rv.is_async = enable_async
 454
 455        return _environment_config_check(rv)
 456
 457    @property
 458    def lexer(self) -> Lexer:
 459        """The lexer for this environment."""
 460        return get_lexer(self)
 461
 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))
 465
 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)
 484
 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)
 497
 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"
 514
 515        func = env_map.get(name)  # type: ignore
 516
 517        if func is None:
 518            msg = f"No {type_name} named {name!r}."
 519
 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?)"
 525
 526            raise TemplateRuntimeError(msg)
 527
 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)
 531
 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                )
 537
 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)
 545
 546            args.insert(0, eval_ctx)
 547        elif pass_arg is _PassArg.environment:
 548            args.insert(0, self)
 549
 550        return func(*args, **kwargs)
 551
 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.
 562
 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.
 566
 567        .. versionadded:: 2.7
 568        """
 569        return self._filter_test_common(
 570            name, value, args, kwargs, context, eval_ctx, True
 571        )
 572
 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.
 583
 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.
 587
 588        .. versionchanged:: 3.0
 589            Tests support ``@pass_context``, etc. decorators. Added
 590            the ``context`` and ``eval_ctx`` parameters.
 591
 592        .. versionadded:: 2.7
 593        """
 594        return self._filter_test_common(
 595            name, value, args, kwargs, context, eval_ctx, False
 596        )
 597
 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.
 609
 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)
 617
 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()
 623
 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.
 634
 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)
 644
 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        )
 660
 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)
 673
 674        for ext in self.iter_extensions():
 675            stream = ext.filter_stream(stream)  # type: ignore
 676
 677            if not isinstance(stream, TokenStream):
 678                stream = TokenStream(stream, name, filename)
 679
 680        return stream
 681
 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.
 691
 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        )
 702
 703    def _compile(self, source: str, filename: str) -> CodeType:
 704        """Internal hook that can be overridden to hook a different compile
 705        method in.
 706
 707        .. versionadded:: 2.5
 708        """
 709        return compile(source, filename, "exec")
 710
 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: ...
 720
 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: ...
 730
 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.
 746
 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.
 751
 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.
 755
 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)
 772
 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.
 779
 780        This is useful if applications want to use the same rules as Jinja
 781        in template "configuration files" or similar situations.
 782
 783        Example usage:
 784
 785        >>> env = Environment()
 786        >>> expr = env.compile_expression('foo == 42')
 787        >>> expr(foo=23)
 788        False
 789        >>> expr(foo=42)
 790        True
 791
 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`.
 795
 796        >>> env.compile_expression('var')() is None
 797        True
 798        >>> env.compile_expression('var', undefined_to_none=False)()
 799        Undefined
 800
 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)
 813
 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)
 817
 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'``.
 832
 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.
 836
 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.
 841
 842        .. versionadded:: 2.4
 843        """
 844        from .loaders import ModuleLoader
 845
 846        if log_function is None:
 847
 848            def log_function(x: str) -> None:
 849                pass
 850
 851        assert log_function is not None
 852        assert self.loader is not None, "No loader configured."
 853
 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"))
 862
 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
 868
 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}")
 877
 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
 888
 889                filename = ModuleLoader.get_module_filename(name)
 890
 891                write_file(filename, code)
 892                log_function(f'Compiled "{name}" as {filename}')
 893        finally:
 894            if zip:
 895                zip_file.close()
 896
 897        log_function("Finished compiling templates")
 898
 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.
 907
 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.
 914
 915        If the loader does not support that, a :exc:`TypeError` is raised.
 916
 917        .. versionadded:: 2.4
 918        """
 919        assert self.loader is not None, "No loader configured."
 920        names = self.loader.list_templates()
 921
 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                )
 927
 928            def filter_func(x: str) -> bool:
 929                return "." in x and x.rsplit(".", 1)[1] in extensions
 930
 931        if filter_func is not None:
 932            names = [name for name in names if filter_func(name)]
 933
 934        return names
 935
 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
 941
 942        raise rewrite_traceback_stack(source=source)
 943
 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.
 950
 951        Subclasses may override this method and implement template path
 952        joining here.
 953        """
 954        return template
 955
 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)
 972
 973                return template
 974
 975        template = self.loader.load(self, name, self.make_globals(globals))
 976
 977        if self.cache is not None:
 978            self.cache[cache_key] = template
 979        return template
 980
 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.
 991
 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.
1002
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.
1006
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)
1015
1016        return self._load_template(name, globals)
1017
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.
1028
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.
1037
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.
1041
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.
1046
1047        .. versionchanged:: 2.4
1048            If ``names`` contains a :class:`Template` object it is
1049            returned unchanged.
1050
1051        .. versionadded:: 2.3
1052        """
1053        if isinstance(names, Undefined):
1054            names._fail_with_undefined_error()
1055
1056        if not names:
1057            raise TemplatesNotFound(
1058                message="Tried to select from an empty list of templates."
1059            )
1060
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
1071
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.
1083
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)
1091
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`.
1100
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)
1112
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`.
1118
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.
1123
1124        :param d: Dict of template-specific globals.
1125
1126        .. versionchanged:: 3.0
1127            Use :class:`collections.ChainMap` to always prevent mutating
1128            environment globals.
1129        """
1130        if d is None:
1131            d = {}
1132
1133        return ChainMap(d, self.globals)
1134
1135
1136class Template:
1137    """A compiled template that can be rendered.
1138
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.
1142
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.
1148
1149    A template object should be considered immutable. Modifications on
1150    the object are not supported.
1151    """
1152
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
1156
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]]
1166
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)
1215
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
1232
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.
1242
1243        .. versionadded:: 2.4
1244        """
1245        return cls._from_namespace(environment, module_dict, globals)
1246
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"]
1260
1261        # render function and module
1262        t.root_render_func = namespace["root"]
1263        t._module = None
1264
1265        # debug and loader helpers
1266        t._debug_info = namespace["debug_info"]
1267        t._uptodate = None
1268
1269        # store the reference
1270        namespace["environment"] = environment
1271        namespace["__jinja_template__"] = t
1272
1273        return t
1274
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::
1279
1280            template.render(knights='that say nih')
1281            template.render({'knights': 'that say nih'})
1282
1283        This will return the rendered template as a string.
1284        """
1285        if self.environment.is_async:
1286            import asyncio
1287
1288            return asyncio.run(self.render_async(*args, **kwargs))
1289
1290        ctx = self.new_context(dict(*args, **kwargs))
1291
1292        try:
1293            return self.environment.concat(self.root_render_func(ctx))  # type: ignore
1294        except Exception:
1295            self.environment.handle_exception()
1296
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.
1301
1302        Example usage::
1303
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            )
1310
1311        ctx = self.new_context(dict(*args, **kwargs))
1312
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()
1319
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))
1325
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.
1331
1332        It accepts the same arguments as :meth:`render`.
1333        """
1334        if self.environment.is_async:
1335            import asyncio
1336
1337            async def to_list() -> t.List[str]:
1338                return [x async for x in self.generate_async(*args, **kwargs)]
1339
1340            yield from asyncio.run(to_list())
1341            return
1342
1343        ctx = self.new_context(dict(*args, **kwargs))
1344
1345        try:
1346            yield from self.root_render_func(ctx)
1347        except Exception:
1348            yield self.environment.handle_exception()
1349
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            )
1360
1361        ctx = self.new_context(dict(*args, **kwargs))
1362
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()
1374
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.
1385
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        )
1391
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)
1406
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        )
1424
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.
1431
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.")
1440
1441        if ctx is not None:
1442            keys = ctx.globals_keys - self.globals.keys()
1443
1444            if keys:
1445                return self.make_module({k: ctx.parent[k] for k in keys})
1446
1447        if self._module is None:
1448            self._module = self.make_module()
1449
1450        return self._module
1451
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()
1457
1458            if keys:
1459                return await self.make_module_async({k: ctx.parent[k] for k in keys})
1460
1461        if self._module is None:
1462            self._module = await self.make_module_async()
1463
1464        return self._module
1465
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:
1471
1472        >>> t = Template('{% macro foo() %}42{% endmacro %}23')
1473        >>> str(t.module)
1474        '23'
1475        >>> t.module.foo() == u'42'
1476        True
1477
1478        This attribute is not available if async mode is enabled.
1479        """
1480        return self._get_default_module()
1481
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
1490
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()
1497
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            ]
1506
1507        return []
1508
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}>"
1515
1516
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    """
1522
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                )
1536
1537            body_stream = list(template.root_render_func(context))
1538
1539        self._body_stream = body_stream
1540        self.__dict__.update(context.get_exported())
1541        self.__name__ = template.name
1542
1543    def __html__(self) -> Markup:
1544        return Markup(concat(self._body_stream))
1545
1546    def __str__(self) -> str:
1547        return concat(self._body_stream)
1548
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}>"
1555
1556
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    """
1562
1563    def __init__(self, template: Template, undefined_to_none: bool) -> None:
1564        self._template = template
1565        self._undefined_to_none = undefined_to_none
1566
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
1574
1575
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.
1581
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    """
1586
1587    def __init__(self, gen: t.Iterator[str]) -> None:
1588        self._gen = gen
1589        self.disable_buffering()
1590
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`.
1600
1601        Example usage::
1602
1603            Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
1604        """
1605        close = False
1606
1607        if isinstance(fp, str):
1608            if encoding is None:
1609                encoding = "utf-8"
1610
1611            real_fp: t.IO[bytes] = open(fp, "wb")
1612            close = True
1613        else:
1614            real_fp = fp
1615
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
1621
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()
1630
1631    def disable_buffering(self) -> None:
1632        """Disable the output buffering."""
1633        self._next = partial(next, self._gen)
1634        self.buffered = False
1635
1636    def _buffered_generator(self, size: int) -> t.Iterator[str]:
1637        buf: t.List[str] = []
1638        c_size = 0
1639        push = buf.append
1640
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
1654
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")
1659
1660        self.buffered = True
1661        self._next = partial(next, self._buffered_generator(size))
1662
1663    def __iter__(self) -> "TemplateStream":
1664        return self
1665
1666    def __next__(self) -> str:
1667        return self._next()  # type: ignore
1668
1669
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