✨ Added sanitization in BatchFile template rendering

xtl.jobs.batchfiles:BatchTemplate
- Added `__MAGIC_VARS__` dictionary to store 'magic' context variables
  (name is XTL*) that get dynamically computed when substituted

xtl.jobs.batchfiles:BatchFile
- The context passed to `BatchTemplate.substitute` is now first
  sanitized (e.g. escaping of paths)
- Magic variables are now expanded and passed along with the context

Author: dtriand

src/xtl/jobs/batchfiles.py

@@ -1,14 +1,17 @@
 from __future__ import annotations
 import asyncio
+from datetime import datetime
+import shlex
 from enum import Enum
 from pathlib import Path
 from string import Template
-from typing import Iterable, TYPE_CHECKING
+from typing import Callable, Iterable, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from xtl.config.settings import DependencySettings
     from xtl.jobs.sites import ComputeSiteType, LocalSite, SchedulerSite
     from xtl.jobs.config2 import BatchJobConfig
+from xtl import version
 from xtl.common.compatibility import PY310_OR_LESS
 from xtl.common.os import FilePermissions
 from xtl.jobs.shells import Shell, ShellType, DefaultShell
@@ -62,6 +65,12 @@ class BatchTemplate(Template):
             )
         '''
 
+    __MAGIC_VARS__: dict[str, Callable] = {
+        'XTL_COMMENT': lambda **kwargs: kwargs.get('comment_char', ''),
+        'XTL_NL': lambda **kwargs: kwargs.get('new_line_char', ''),
+        'XTL_DOCSTRING': lambda **kwargs: f'Generated by xtl {version} on {datetime.now().isoformat()}',
+    }
+
 
 class BatchFile:
 
@@ -285,8 +294,45 @@ async def cancel(self):
         """
         await self.compute_site.cancel_batch(self)
 
-    @staticmethod
-    def _render_template(template: str, context: dict) -> str:
+    def _magic_context(self) -> dict:
+        """
+        Returns a dictionary of "magic" context variables that can be used in batch file
+        templates. These variables are automatically generated and can be accessed in
+        templates using their keys (e.g., `__XTL_DOCSTRING__`).
+        """
+        kwargs = {
+            'new_line_char': self.shell.new_line_char,
+            'comment_char': self.shell.comment_char,
+        }
+        return {var: func(**kwargs) for var, func in BatchTemplate.__MAGIC_VARS__.items()}
+
+    def _sanitize_context(self, context: dict) -> dict:
+        """
+        Sanitize the context dictionary for safe insertion into batch file templates.
+        """
+        sanitized = {}
+        for key, value in context.items():
+            match value:
+                case Path():
+                    path_str = str(value)
+                    if self.shell.is_posix:
+                        # Use shlex.quote to properly escape the path for POSIX shells
+                        sanitized[key] = shlex.quote(path_str)
+                    elif self.shell == Shell.CMD:  # CMD requires double quotes for escaping
+                        # Escape internal quotes by doubling them
+                        path_str = path_str.replace('"', '""')
+                        sanitized[key] = f'"{path_str}"'
+                    elif self.shell == Shell.POWERSHELL:  # PWSH requires single quotes for escaping
+                        # Escape internal quotes by doubling them
+                        path_str = path_str.replace('\'', '\'\'')
+                        sanitized[key] = f'\'{path_str}\''
+                    else:
+                        raise ValueError(f'Unsupported shell for path sanitization: {self.shell}')
+                case _:
+                    sanitized[key] = value
+        return sanitized
+
+    def _render_template(self, template: str, context: dict = None) -> str:
         """
         Render a batch file template with the given context.
 
@@ -298,7 +344,13 @@ def _render_template(template: str, context: dict) -> str:
         :raises ValueError: If the `template` contains invalid placeholders.
         """
         batch_template = BatchTemplate(template)
-        return batch_template.substitute(context or {})
+        try:
+            magic = self._magic_context()
+            sanitized = self._sanitize_context(context or {})
+            return batch_template.substitute(sanitized | magic)
+        except KeyError as e:
+            missing_key = e.args[0]
+            raise KeyError(f'Missing required key for {BatchFile.__name__} template: {missing_key}')
 
     @classmethod
     def from_config(cls, config: BatchJobConfig | dict, context: dict = None) \