feat: Don't fail just warn about undefined Jinja variables

Stumbled over this when I used an existing template for --create-from.
Maybe introduce a --fail-undefined-vars option later.

Author: dannyadair

src/pdfbaker/page.py

@@ -8,6 +8,7 @@
 
 from pathlib import Path
 
+import jinja2
 from jinja2.exceptions import TemplateError, TemplateNotFound
 
 from .config import PathSpec
@@ -30,29 +31,22 @@ def __init__(self, config_path: PathSpec, page_number: int, **kwargs):
         )
         self.log_trace(self.config.readable())
 
-    def process(self) -> Path:
-        """Render SVG template and convert to PDF."""
-        self.log_debug_subsection(
-            "Processing page %d: %s", self.config.page_number, self.config.name
-        )
-
-        self.log_debug("Loading template: %s", self.config.template.name)
-        if self.logger.isEnabledFor(TRACE):
-            with open(self.config.template.path, encoding="utf-8") as f:
-                self.log_trace_preview(f.read())
-
+    def _load_jinja_template(self, undefined_vars) -> jinja2.Template:
         try:
-            jinja_extensions = self.config.jinja2_extensions
-            if jinja_extensions:
-                self.log_debug("Using Jinja2 extensions: %s", jinja_extensions)
+            if self.config.jinja2_extensions:
+                self.log_debug(
+                    "Using Jinja2 extensions: %s", self.config.jinja2_extensions
+                )
             jinja_env = create_env(
                 templates_dir=self.config.template.path.parent,
-                extensions=jinja_extensions,
+                extensions=self.config.jinja2_extensions,
                 template_filters=[
                     filter.value for filter in self.config.template_filters
                 ],
+                undefined_vars=undefined_vars,
+                template_file=str(self.config.template.path),
             )
-            template = jinja_env.get_template(self.config.template.path.name)
+            return jinja_env.get_template(self.config.template.path.name)
         except TemplateNotFound as exc:
             raise SVGTemplateError(
                 "Failed to load template for page "
@@ -64,16 +58,31 @@ def process(self) -> Path:
                 f"{self.config.page_number} ({self.config.name}): {exc}"
             ) from exc
 
+    def process(self) -> Path:
+        """Render SVG template and convert to PDF."""
+        self.log_debug_subsection(
+            "Processing page %d: %s", self.config.page_number, self.config.name
+        )
+
+        self.log_debug("Loading template: %s", self.config.template.name)
+        if self.logger.isEnabledFor(TRACE):
+            with open(self.config.template.path, encoding="utf-8") as f:
+                self.log_trace_preview(f.read())
+
+        undefined_vars = set()
+        template = self._load_jinja_template(undefined_vars)
+
         context = self.config.resolve_variables().model_dump()
         template_context = prepare_template_context(
             context=context,
             images_dir=self.config.directories.images,
         )
 
         build_dir = self.config.directories.build
-        name = self.config.name
         if self.config.is_variant:
-            name = f'{name}_{self.config.variant["name"]}'
+            name = f'{self.config.name}_{self.config.variant["name"]}'
+        else:
+            name = self.config.name
         output_svg = build_dir / f"{self.config.page_number:03}_{name}.svg"
         output_pdf = build_dir / f"{self.config.page_number:03}_{name}.pdf"
 
@@ -85,6 +94,13 @@ def process(self) -> Path:
                     renderer.value for renderer in self.config.template_renderers
                 ],
             )
+            if undefined_vars:
+                for var, template_file in sorted(undefined_vars):
+                    self.log_warning(
+                        'Undefined variable "%s" in template %s',
+                        var,
+                        template_file,
+                    )
             if self.config.dry_run:
                 self.log_debug(
                     "👀 [DRY RUN] Not writing rendered template to %s", output_svg

src/pdfbaker/render.py

@@ -71,19 +71,85 @@ def replacer(match: re.Match[str]) -> str:
     return rendered
 
 
+class PDFBakerUndefined(jinja2.Undefined):
+    """Custom Undefined that collects undefined variable names and template file."""
+
+    def __init__(self, *args, undefined_vars=None, template_file=None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._undefined_vars = undefined_vars
+        self._template_file = template_file
+        if self._undefined_vars is not None and self._undefined_name is not None:
+            self._undefined_vars.add((self._undefined_name, self._template_file))
+
+    def _fail_with_undefined_error(self, *args, **kwargs):
+        if self._undefined_vars is not None and self._undefined_name is not None:
+            self._undefined_vars.add((self._undefined_name, self._template_file))
+        return ""
+
+    def __str__(self):
+        return self._fail_with_undefined_error()
+
+    def __getattr__(self, name):
+        return self._fail_with_undefined_error()
+
+    def __call__(self, *args, **kwargs):
+        return self._fail_with_undefined_error()
+
+    def __iter__(self):
+        # Allows {% for ... in ... %} to not fail
+        self._fail_with_undefined_error()
+        return iter([])
+
+    def __bool__(self):
+        # Allows {% if ... %} to not fail
+        self._fail_with_undefined_error()
+        return False
+
+    def __len__(self):
+        self._fail_with_undefined_error()
+        return 0
+
+    def __getitem__(self, key):
+        # Allows {{ ...[0].something }} to not fail
+        return self._fail_with_undefined_error()
+
+
 def create_env(
     templates_dir: Path | None = None,
     extensions: list[str] | None = None,
     template_filters: list[str] | None = None,
+    undefined_vars: set | None = None,
+    template_file: str | None = None,
 ) -> jinja2.Environment:
-    """Create and configure the Jinja environment."""
+    """Create and configure the Jinja environment.
+
+    Args:
+        templates_dir: Directory containing templates
+        extensions: List of Jinja2 extensions
+        template_filters: List of template filter names
+        undefined_vars: Set to collect (var, template_file) tuples for undefined vars
+        template_file: Name of the template file being rendered (for error reporting)
+    """
     if templates_dir is None:
         raise ValueError("templates_dir is required")
 
+    # pylint: disable=too-few-public-methods
+    class CustomUndefined(PDFBakerUndefined):
+        """Undefined class that collects undefined variables per template."""
+
+        def __init__(self, *args, **kwargs):
+            super().__init__(
+                *args,
+                undefined_vars=undefined_vars,
+                template_file=template_file,
+                **kwargs,
+            )
+
     env = jinja2.Environment(
         loader=jinja2.FileSystemLoader(str(templates_dir)),
         autoescape=jinja2.select_autoescape(),
         extensions=extensions or [],
+        undefined=CustomUndefined,
     )
     env.template_class = PDFBakerTemplate