Merge pull request #465 from flyingcircusio/356-add-variable-for-gene…

…rated-header

Add variable `batou_generated_header` to global template rendering context

CHANGES.md

@@ -6,6 +6,9 @@
 
 - Fix unsatisfied resource message if a host-specific resource is not
   satisfied. (#463)
+- Adds variable `batou_generated_header` to global template rendering
+  context. This variable contains a comment block that signals that
+  the file content is generated by batou. (#356)
 
 
 ## 2.5.0b3 (2024-08-05)

src/batou/component.py

@@ -17,6 +17,13 @@
 from batou.utils import call_with_optional_args
 
 
+# batou_generated_header = """\
+# File is generated by batou. Don't edit manually."""
+def batou_generated_header(component):
+    return f"""\
+File is generated by batou for component {component._breadcrumbs}. Don't edit manually."""
+
+
 def platform(name, component):
     """Class decorator to register a component class as a platform-component
     for the given platform and component.
@@ -888,6 +895,15 @@ def expand(self, string, component=None, **kw):
         built-in string templates, to keep your inline configuration
         in sync with the external file templating based on Jinja2.
 
+        The following variables are available in the template context:
+
+        - ``host``: The host object this component is configured for.
+        - ``environment``: The environment object this component is configured
+          for.
+        - ``component``: The component object this component is configured for.
+        - ``batou_generated_header``: A string that can be used to mark
+            generated files.
+
         :param unicode string: The string you want to be expanded as a Jinja2
             template.
 
@@ -916,6 +932,15 @@ def template(self, filename, component=None):
         can expand a file and receive a unicode string (instead of directly
         rendering the file to a target location).
 
+        The following variables are available in the template context:
+
+        - ``host``: The host object this component is configured for.
+        - ``environment``: The environment object this component is configured
+            for.
+        - ``component``: The component object this component is configured for.
+        - ``batou_generated_header``: A string that can be used to mark
+            generated files.
+
         :param str filename: The file you want to expand. The filename is
             **not** mapped by this function. Map the filename before calling
             ``template`` if needed.
@@ -945,6 +970,7 @@ def _template_args(self, component=None, **kw):
             host=component.host,
             environment=component.environment,
             component=component,
+            batou_generated_header=batou_generated_header(component),
         )
         args.update(kw)
         return args

src/batou/tests/test_component.py

@@ -417,6 +417,14 @@ def test_templates(root):
     assert root.component.template("sample") == ("Hello localhost\n")
 
 
+def test_template_batou_generated_header(root):
+    with open("sample", "w") as template:
+        template.write("Hello\n# {{batou_generated_header}}")
+    assert root.component.template("sample") == (
+        "Hello\n# File is generated by batou for component MyComponent. Don't edit manually.\n"
+    )
+
+
 def test_chdir_contextmanager_is_stackable():
     outer = os.getcwd()
     inner1 = os.path.join(os.path.dirname(__file__), "fixture")