Add new comment attribute to template plugin (#69253)

* Add new comment attribute to template plugin

Add comment_start_string and comment_end_string attribute to template
plugin


Co-authored-by: Hossein Zolfi <h.zolfi@inside.sahab.ir>

changelogs/fragments/69253-template-comment-attribute.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - template - Add comment attributes (``comment_start_string`` and ``comment_end_string``)

lib/ansible/plugins/action/template.py

@@ -37,7 +37,7 @@ class ActionModule(ActionBase):
         # Options type validation
         # stings
         for s_type in ('src', 'dest', 'state', 'newline_sequence', 'variable_start_string', 'variable_end_string', 'block_start_string',
-                       'block_end_string'):
+                       'block_end_string', 'comment_start_string', 'comment_end_string'):
             if s_type in self._task.args:
                 value = ensure_type(self._task.args[s_type], 'string')
                 if value is not None and not isinstance(value, string_types):
@@ -61,6 +61,8 @@ class ActionModule(ActionBase):
         variable_end_string = self._task.args.get('variable_end_string', None)
         block_start_string = self._task.args.get('block_start_string', None)
         block_end_string = self._task.args.get('block_end_string', None)
+        comment_start_string = self._task.args.get('comment_start_string', None)
+        comment_end_string = self._task.args.get('comment_end_string', None)
         output_encoding = self._task.args.get('output_encoding', 'utf-8') or 'utf-8'
 
         # Option `lstrip_blocks' was added in Jinja2 version 2.7.
@@ -140,6 +142,8 @@ class ActionModule(ActionBase):
                                                           block_end_string=block_end_string,
                                                           variable_start_string=variable_start_string,
                                                           variable_end_string=variable_end_string,
+                                                          comment_start_string=comment_start_string,
+                                                          comment_end_string=comment_end_string,
                                                           trim_blocks=trim_blocks,
                                                           lstrip_blocks=lstrip_blocks,
                                                           available_variables=temp_vars)
@@ -158,7 +162,7 @@ class ActionModule(ActionBase):
 
             # remove 'template only' options:
             for remove in ('newline_sequence', 'block_start_string', 'block_end_string', 'variable_start_string', 'variable_end_string',
-                           'trim_blocks', 'lstrip_blocks', 'output_encoding'):
+                           'comment_start_string', 'comment_end_string', 'trim_blocks', 'lstrip_blocks', 'output_encoding'):
                 new_task.args.pop(remove, None)
 
             local_tempdir = tempfile.mkdtemp(dir=C.DEFAULT_LOCAL_TMP)

lib/ansible/plugins/doc_fragments/template_common.py

@@ -69,6 +69,16 @@ options:
     type: str
     default: '}}'
     version_added: '2.4'
+  comment_start_string:
+    description:
+    - The string marking the beginning of a comment statement.
+    type: str
+    version_added: '2.12'
+  comment_end_string:
+    description:
+    - The string marking the end of a comment statement.
+    type: str
+    version_added: '2.12'
   trim_blocks:
     description:
     - Determine when newlines should be removed from blocks.

lib/ansible/plugins/lookup/template.py

@@ -45,6 +45,14 @@ DOCUMENTATION = """
         default: {}
         version_added: '2.3'
         type: dict
+      comment_start_string:
+        description: The string marking the beginning of a comment statement.
+        version_added: '2.12'
+        type: str
+      comment_end_string:
+        description: The string marking the end of a comment statement.
+        version_added: '2.12'
+        type: str
 """
 
 EXAMPLES = """
@@ -55,6 +63,10 @@ EXAMPLES = """
 - name: show templating results with different variable start and end string
   debug:
     msg: "{{ lookup('template', './some_template.j2', variable_start_string='[%', variable_end_string='%]') }}"
+
+- name: show templating results with different comment start and end string
+  debug:
+    msg: "{{ lookup('template', './some_template.j2', comment_start_string='[#', comment_end_string='#]') }}"
 """
 
 RETURN = """
@@ -94,6 +106,8 @@ class LookupModule(LookupBase):
         jinja2_native = self.get_option('jinja2_native')
         variable_start_string = self.get_option('variable_start_string')
         variable_end_string = self.get_option('variable_end_string')
+        comment_start_string = self.get_option('comment_start_string')
+        comment_end_string = self.get_option('comment_end_string')
 
         if USE_JINJA2_NATIVE and not jinja2_native:
             templar = self._templar.copy_with_new_env(environment_class=AnsibleEnvironment)
@@ -132,6 +146,8 @@ class LookupModule(LookupBase):
 
                 with templar.set_temporary_context(variable_start_string=variable_start_string,
                                                    variable_end_string=variable_end_string,
+                                                   comment_start_string=comment_start_string,
+                                                   comment_end_string=comment_end_string,
                                                    available_variables=vars, searchpath=searchpath):
                     res = templar.template(template_data, preserve_trailing_newlines=True,
                                            convert_data=convert_data_p, escape_backslashes=False)

test/integration/targets/lookup_template/tasks/main.yml

@@ -17,3 +17,11 @@
 - assert:
     that:
       - "hello_world_string|trim == 'Hello world!'"
+
+- name: Test that we have a proper jinja search path in template lookup with different comment start and end string
+  set_fact:
+    hello_world_comment: "{{ lookup('template', 'hello_comment.txt', comment_start_string='[#', comment_end_string='#]') }}"
+
+- assert:
+    that:
+      - "hello_world_comment|trim == 'Hello world!'"

test/integration/targets/lookup_template/templates/hello_comment.txt

@@ -0,0 +1,2 @@
+[# Comment #]
+Hello world!

test/integration/targets/template/files/custom_comment_string.expected

@@ -0,0 +1,2 @@
+Before
+After

test/integration/targets/template/tasks/main.yml

@@ -141,6 +141,26 @@
         - 'import_as_with_context_diff_result.stdout == ""'
         - "import_as_with_context_diff_result.rc == 0"
 
+# VERIFY comment_start_string and comment_end_string
+
+- name: Render a template with "comment_start_string" set to [#
+  template:
+    src: custom_comment_string.j2
+    dest: "{{output_dir}}/custom_comment_string.templated"
+    comment_start_string: "[#"
+    comment_end_string: "#]"
+  register: custom_comment_string_result
+
+- name: Get checksum of known good custom_comment_string.expected
+  stat:
+    path: "{{role_path}}/files/custom_comment_string.expected"
+  register: custom_comment_string_good
+
+- name: Verify templated custom_comment_string matches known good using checksum
+  assert:
+    that:
+        - "custom_comment_string_result.checksum == custom_comment_string_good.stat.checksum"
+
 # VERIFY trim_blocks
 
 - name: Render a template with "trim_blocks" set to False

test/integration/targets/template/templates/custom_comment_string.j2

@@ -0,0 +1,3 @@
+Before
+[# Test comment_start_string #]
+After