Skip to content

Commit

Permalink
Add Environment.extract_parsed_names to support tracking dynamic inhe…
Browse files Browse the repository at this point in the history
…ritance or inclusion
  • Loading branch information
infinity0 committed Dec 15, 2022
1 parent ae53ea5 commit dc0f8d5
Show file tree
Hide file tree
Showing 5 changed files with 65 additions and 1 deletion.
3 changes: 3 additions & 0 deletions CHANGES.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ Version 3.2.0

Unreleased

- Add ``Environment.extract_parsed_names`` to support tracking dynamic
inheritance or inclusion. :issue:`1776`


Version 3.1.2
-------------
Expand Down
2 changes: 2 additions & 0 deletions docs/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,8 @@ useful if you want to dig deeper into Jinja or :ref:`develop extensions

.. automethod:: overlay([options])

.. automethod:: extract_parsed_names()

.. method:: undefined([hint, obj, name, exc])

Creates a new :class:`Undefined` object for `name`. This is useful
Expand Down
39 changes: 39 additions & 0 deletions src/jinja2/environment.py
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,11 @@ class Environment:
`enable_async`
If set to true this enables async template execution which
allows using async functions and generators.
`remember_parsed_names`
Should we remember parsed names? This is useful for dynamic
dependency tracking, see `extract_parsed_names` for details.
Default is ``False``.
"""

#: if this environment is sandboxed. Modifying this variable won't make
Expand Down Expand Up @@ -313,6 +318,7 @@ def __init__(
auto_reload: bool = True,
bytecode_cache: t.Optional["BytecodeCache"] = None,
enable_async: bool = False,
remember_parsed_names: bool = False,
):
# !!Important notice!!
# The constructor accepts quite a few arguments that should be
Expand Down Expand Up @@ -365,6 +371,11 @@ def __init__(
self.is_async = enable_async
_environment_config_check(self)

# dependency tracking
self.parsed_names: t.Optional[t.List[str]] = (
[] if remember_parsed_names else None
)

def add_extension(self, extension: t.Union[str, t.Type["Extension"]]) -> None:
"""Adds an extension after the environment was created.
Expand Down Expand Up @@ -614,8 +625,36 @@ def _parse(
self, source: str, name: t.Optional[str], filename: t.Optional[str]
) -> nodes.Template:
"""Internal parsing function used by `parse` and `compile`."""
if name is not None and self.parsed_names is not None:
self.parsed_names.append(name)
return Parser(self, source, name, filename).parse()

def extract_parsed_names(self) -> t.Optional[t.List[str]]:
"""Return all template names that have been parsed so far, and clear the list.
This is enabled if `remember_parsed_names = True` was passed to the
`Environment` constructor, otherwise it returns `None`. It can be used
after `Template.render()` to extract dependency information. Compared
to `jinja2.meta.find_referenced_templates()`, it:
a. works on dynamic inheritance and includes
b. does not work unless and until you actually render the template
Many buildsystems are unable to support (b), but some do e.g. [1], the
key point being that if the target file does not exist, dependency
information is not needed since the target file must be built anyway.
In such cases, you may prefer this function due to (a).
[1] https://make.mad-scientist.net/papers/advanced-auto-dependency-generation/
.. versionadded:: 3.2
"""
if self.parsed_names is None:
return None
names = self.parsed_names[:]
self.parsed_names.clear()
return names

def lex(
self,
source: str,
Expand Down
4 changes: 3 additions & 1 deletion src/jinja2/meta.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,9 @@ def find_referenced_templates(ast: nodes.Template) -> t.Iterator[t.Optional[str]
['layout.html', None]
This function is useful for dependency tracking. For example if you want
to rebuild parts of the website after a layout template has changed.
to rebuild parts of the website after a layout template has changed. For
an alternative method with different pros and cons, see
`Environment.extract_parsed_names()`.
"""
template_name: t.Any

Expand Down
18 changes: 18 additions & 0 deletions tests/test_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,24 @@ def test_item_and_attribute(self, env):
tmpl = env.from_string('{{ foo["items"] }}')
assert tmpl.render(foo={"items": 42}) == "42"

def test_extract_parsed_names(self, env):
templates = DictLoader(
{
"main": "{% set tpl = 'ba' + 'se' %}{% extends tpl %}",
"base": "{% set tpl = 'INC' %}{% include tpl.lower() %}",
"inc": "whatever",
}
)
env.loader = templates
assert env.get_template("main").render() == "whatever"
assert env.extract_parsed_names() is None

env = Environment(remember_parsed_names=True)
env.loader = templates
assert env.get_template("main").render() == "whatever"
assert env.extract_parsed_names() == ["main", "base", "inc"]
assert env.extract_parsed_names() == []

def test_finalize(self):
e = Environment(finalize=lambda v: "" if v is None else v)
t = e.from_string("{% for item in seq %}|{{ item }}{% endfor %}")
Expand Down

0 comments on commit dc0f8d5

Please sign in to comment.