diff --git a/docxtpl/template.py b/docxtpl/template.py index f20280a..e7f334f 100644 --- a/docxtpl/template.py +++ b/docxtpl/template.py @@ -16,7 +16,7 @@ from docx.opc.part import XmlPart import docx.oxml.ns from docx.opc.constants import RELATIONSHIP_TYPE as REL_TYPE -from jinja2 import Environment, Template, meta +from jinja2 import Environment, Template, meta, nodes from jinja2.exceptions import TemplateError try: @@ -895,7 +895,14 @@ def get_undeclared_template_variables( self, jinja_env: Optional[Environment] = None, context: Optional[Dict[str, Any]] = None, + nested: bool = False, ) -> Set[str]: + """Return the names of the variables the template uses but does not define. + + With nested=True the attribute and string-key lookups on those variables are + returned as dotted paths, so {{ foo.bar }} and {{ foo["bar"] }} both give + "foo.bar" instead of "foo". + """ # Create a temporary document to analyze the template without affecting the current state temp_doc = Document(self.template_file) @@ -920,8 +927,39 @@ def get_undeclared_template_variables( # If context is provided, return only variables that are not in the context if context is not None: - provided_variables = set(context.keys()) - return all_variables - provided_variables + all_variables = all_variables - set(context.keys()) + + if nested: + return self._nested_variable_paths(parse_content, all_variables) - # If no context provided, return all variables (original behavior) return all_variables + + @staticmethod + def _nested_variable_paths(ast: nodes.Template, names: Set[str]) -> Set[str]: + def lookup_path(node: nodes.Node) -> Optional[list]: + if isinstance(node, nodes.Name): + return [node.name] + if isinstance(node, nodes.Getattr): + base = lookup_path(node.node) + return None if base is None else base + [node.attr] + if isinstance(node, nodes.Getitem): + key = node.arg + if isinstance(key, nodes.Const) and isinstance(key.value, str): + base = lookup_path(node.node) + return None if base is None else base + [key.value] + return None + + paths: Set[str] = set() + + def visit(node: nodes.Node) -> None: + if isinstance(node, (nodes.Name, nodes.Getattr, nodes.Getitem)): + path = lookup_path(node) + if path is not None: + if path[0] in names: + paths.add(".".join(path)) + return + for child in node.iter_child_nodes(): + visit(child) + + visit(ast) + return paths diff --git a/tests/get_undeclared_variables_nested.py b/tests/get_undeclared_variables_nested.py new file mode 100644 index 0000000..1ddbeae --- /dev/null +++ b/tests/get_undeclared_variables_nested.py @@ -0,0 +1,57 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +""" +Test for the nested option of get_undeclared_template_variables +""" + +import os + +from docx import Document + +from docxtpl import DocxTemplate + +TEMPLATE_PATH = "output/get_undeclared_variables_nested_tpl.docx" + + +def make_template(): + os.makedirs("output", exist_ok=True) + doc = Document() + doc.add_paragraph("{{ foo.bar }} {{ foo['baz'] }} {{ plain }}") + doc.add_paragraph("{{ order.customer.name }} {{ items[0] }}") + doc.add_paragraph("{% for row in rows %}{{ row.id }} {{ other.value }}{% endfor %}") + doc.save(TEMPLATE_PATH) + + +def test_nested(): + make_template() + tpl = DocxTemplate(TEMPLATE_PATH) + expected = { + "foo.bar", + "foo.baz", + "plain", + "order.customer.name", + "items", + "rows", + "other.value", + } + found = tpl.get_undeclared_template_variables(nested=True) + assert found == expected, found + + # the default behavior still returns the top level names only + assert tpl.get_undeclared_template_variables() == { + "foo", + "plain", + "order", + "items", + "rows", + "other", + } + + # variables given in the context are left out + found = tpl.get_undeclared_template_variables(context={"foo": {}}, nested=True) + assert found == expected - {"foo.bar", "foo.baz"}, found + + +if __name__ == "__main__": + test_nested() + print("PASS: nested undeclared variables")