Enhancement: jinja template support for workflow title assignment (#10700)

---------

Co-authored-by: Trenton Holmes <797416+stumpylog@users.noreply.github.com>
Co-authored-by: shamoon <4887959+shamoon@users.noreply.github.com>

src/documents/templating/environment.py

@@ -0,0 +1,27 @@
+from jinja2.sandbox import SandboxedEnvironment
+
+
+class JinjaEnvironment(SandboxedEnvironment):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.undefined_tracker = None
+
+    def is_safe_callable(self, obj):
+        # Block access to .save() and .delete() methods
+        if callable(obj) and getattr(obj, "__name__", None) in (
+            "save",
+            "delete",
+            "update",
+        ):
+            return False
+        # Call the parent method for other cases
+        return super().is_safe_callable(obj)
+
+
+_template_environment = JinjaEnvironment(
+    trim_blocks=True,
+    lstrip_blocks=True,
+    keep_trailing_newline=False,
+    autoescape=False,
+    extensions=["jinja2.ext.loopcontrols"],
+)

src/documents/templating/filepath.py

@@ -2,22 +2,16 @@ import logging
 import os
 import re
 from collections.abc import Iterable
-from datetime import date
-from datetime import datetime
 from pathlib import PurePath
 
 import pathvalidate
-from babel import Locale
-from babel import dates
 from django.utils import timezone
-from django.utils.dateparse import parse_date
 from django.utils.text import slugify as django_slugify
 from jinja2 import StrictUndefined
 from jinja2 import Template
 from jinja2 import TemplateSyntaxError
 from jinja2 import UndefinedError
 from jinja2 import make_logging_undefined
-from jinja2.sandbox import SandboxedEnvironment
 from jinja2.sandbox import SecurityError
 
 from documents.models import Correspondent
@@ -27,39 +21,16 @@ from documents.models import Document
 from documents.models import DocumentType
 from documents.models import StoragePath
 from documents.models import Tag
+from documents.templating.environment import _template_environment
+from documents.templating.filters import format_datetime
+from documents.templating.filters import get_cf_value
+from documents.templating.filters import localize_date
 
 logger = logging.getLogger("paperless.templating")
 
 _LogStrictUndefined = make_logging_undefined(logger, StrictUndefined)
 
 
-class FilePathEnvironment(SandboxedEnvironment):
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self.undefined_tracker = None
-
-    def is_safe_callable(self, obj):
-        # Block access to .save() and .delete() methods
-        if callable(obj) and getattr(obj, "__name__", None) in (
-            "save",
-            "delete",
-            "update",
-        ):
-            return False
-        # Call the parent method for other cases
-        return super().is_safe_callable(obj)
-
-
-_template_environment = FilePathEnvironment(
-    trim_blocks=True,
-    lstrip_blocks=True,
-    keep_trailing_newline=False,
-    autoescape=False,
-    extensions=["jinja2.ext.loopcontrols"],
-    undefined=_LogStrictUndefined,
-)
-
-
 class FilePathTemplate(Template):
     def render(self, *args, **kwargs) -> str:
         def clean_filepath(value: str) -> str:
@@ -81,54 +52,7 @@ class FilePathTemplate(Template):
         return clean_filepath(original_render)
 
 
-def get_cf_value(
-    custom_field_data: dict[str, dict[str, str]],
-    name: str,
-    default: str | None = None,
-) -> str | None:
-    if name in custom_field_data and custom_field_data[name]["value"] is not None:
-        return custom_field_data[name]["value"]
-    elif default is not None:
-        return default
-    return None
-
-
-def format_datetime(value: str | datetime, format: str) -> str:
-    if isinstance(value, str):
-        value = parse_date(value)
-    return value.strftime(format=format)
-
-
-def localize_date(value: date | datetime, format: str, locale: str) -> str:
-    """
-    Format a date or datetime object into a localized string using Babel.
-
-    Args:
-        value (date | datetime): The date or datetime to format. If a datetime
-            is provided, it should be timezone-aware (e.g., UTC from a Django DB object).
-        format (str): The format to use. Can be one of Babel's preset formats
-            ('short', 'medium', 'long', 'full') or a custom pattern string.
-        locale (str): The locale code (e.g., 'en_US', 'fr_FR') to use for
-            localization.
-
-    Returns:
-        str: The localized, formatted date string.
-
-    Raises:
-        TypeError: If `value` is not a date or datetime instance.
-    """
-    try:
-        Locale.parse(locale)
-    except Exception as e:
-        raise ValueError(f"Invalid locale identifier: {locale}") from e
-
-    if isinstance(value, datetime):
-        return dates.format_datetime(value, format=format, locale=locale)
-    elif isinstance(value, date):
-        return dates.format_date(value, format=format, locale=locale)
-    else:
-        raise TypeError(f"Unsupported type {type(value)} for localize_date")
-
+_template_environment.undefined = _LogStrictUndefined
 
 _template_environment.filters["get_cf_value"] = get_cf_value
 

src/documents/templating/filters.py

@@ -0,0 +1,60 @@
+from datetime import date
+from datetime import datetime
+
+from babel import Locale
+from babel import dates
+from django.utils.dateparse import parse_date
+from django.utils.dateparse import parse_datetime
+
+
+def localize_date(value: date | datetime | str, format: str, locale: str) -> str:
+    """
+    Format a date, datetime or str object into a localized string using Babel.
+
+    Args:
+        value (date | datetime | str): The date or datetime to format. If a datetime
+            is provided, it should be timezone-aware (e.g., UTC from a Django DB object).
+            if str is provided is is parsed as date.
+        format (str): The format to use. Can be one of Babel's preset formats
+            ('short', 'medium', 'long', 'full') or a custom pattern string.
+        locale (str): The locale code (e.g., 'en_US', 'fr_FR') to use for
+            localization.
+
+    Returns:
+        str: The localized, formatted date string.
+
+    Raises:
+        TypeError: If `value` is not a date, datetime or str instance.
+    """
+    if isinstance(value, str):
+        value = parse_datetime(value)
+
+    try:
+        Locale.parse(locale)
+    except Exception as e:
+        raise ValueError(f"Invalid locale identifier: {locale}") from e
+
+    if isinstance(value, datetime):
+        return dates.format_datetime(value, format=format, locale=locale)
+    elif isinstance(value, date):
+        return dates.format_date(value, format=format, locale=locale)
+    else:
+        raise TypeError(f"Unsupported type {type(value)} for localize_date")
+
+
+def format_datetime(value: str | datetime, format: str) -> str:
+    if isinstance(value, str):
+        value = parse_date(value)
+    return value.strftime(format=format)
+
+
+def get_cf_value(
+    custom_field_data: dict[str, dict[str, str]],
+    name: str,
+    default: str | None = None,
+) -> str | None:
+    if name in custom_field_data and custom_field_data[name]["value"] is not None:
+        return custom_field_data[name]["value"]
+    elif default is not None:
+        return default
+    return None

src/documents/templating/workflows.py

@@ -1,7 +1,33 @@
+import logging
 from datetime import date
 from datetime import datetime
 from pathlib import Path
 
+from django.utils.text import slugify as django_slugify
+from jinja2 import StrictUndefined
+from jinja2 import Template
+from jinja2 import TemplateSyntaxError
+from jinja2 import UndefinedError
+from jinja2 import make_logging_undefined
+from jinja2.sandbox import SecurityError
+
+from documents.templating.environment import _template_environment
+from documents.templating.filters import format_datetime
+from documents.templating.filters import localize_date
+
+logger = logging.getLogger("paperless.templating")
+
+_LogStrictUndefined = make_logging_undefined(logger, StrictUndefined)
+
+
+_template_environment.undefined = _LogStrictUndefined
+
+_template_environment.filters["datetime"] = format_datetime
+
+_template_environment.filters["slugify"] = django_slugify
+
+_template_environment.filters["localize_date"] = localize_date
+
 
 def parse_w_workflow_placeholders(
     text: str,
@@ -20,6 +46,7 @@ def parse_w_workflow_placeholders(
     e.g. for pre-consumption triggers created will not have been parsed yet, but it will
     for added / updated triggers
     """
+
     formatting = {
         "correspondent": correspondent_name,
         "document_type": doc_type_name,
@@ -52,4 +79,28 @@ def parse_w_workflow_placeholders(
         formatting.update({"doc_title": doc_title})
     if doc_url is not None:
         formatting.update({"doc_url": doc_url})
-    return text.format(**formatting).strip()
+
+    logger.debug(f"Jinja Template is : {text}")
+    try:
+        template = _template_environment.from_string(
+            text,
+            template_class=Template,
+        )
+        rendered_template = template.render(formatting)
+
+        # We're good!
+        return rendered_template
+    except UndefinedError as e:
+        # The undefined class logs this already for us
+        raise e
+    except TemplateSyntaxError as e:
+        logger.warning(f"Template syntax error in title generation: {e}")
+    except SecurityError as e:
+        logger.warning(f"Template attempted restricted operation: {e}")
+    except Exception as e:
+        logger.warning(f"Unknown error in title generation: {e}")
+        logger.warning(
+            f"Invalid title format '{text}', workflow not applied: {e}",
+        )
+        raise e
+    return None