feat(unparse): add limited XML comment round-trip; unify _emit behavior

- Emit `#comment` at any depth via `_emit`, preserving dict order
- Support top‑level comments without tripping multiple roots (lazy validation)
- Use `_XMLGenerator.comment` for output
- Add tests for element/top‑level comments and round‑trip behavior

Author: martinblech

tests/test_dicttoxml.py

@@ -144,6 +144,26 @@ def test_pretty_print(self):
         self.assertEqual(xml, unparse(obj, pretty=True,
                                       newl=newl, indent=indent))
 
+    def test_unparse_with_element_comment(self):
+        obj = {"a": {"#comment": "note", "b": "1"}}
+        xml = _strip(unparse(obj, full_document=True))
+        self.assertEqual(xml, "<a><!--note--><b>1</b></a>")
+
+    def test_unparse_with_multiple_element_comments(self):
+        obj = {"a": {"#comment": ["n1", "n2"], "b": "1"}}
+        xml = _strip(unparse(obj, full_document=True))
+        self.assertEqual(xml, "<a><!--n1--><!--n2--><b>1</b></a>")
+
+    def test_unparse_with_top_level_comment(self):
+        obj = {"#comment": "top", "a": "1"}
+        xml = _strip(unparse(obj, full_document=True))
+        self.assertEqual(xml, "<!--top--><a>1</a>")
+
+    def test_unparse_with_multiple_top_level_comments(self):
+        obj = {"#comment": ["t1", "t2"], "a": "1"}
+        xml = _strip(unparse(obj, full_document=True))
+        self.assertEqual(xml, "<!--t1--><!--t2--><a>1</a>")
+
     def test_pretty_print_with_int_indent(self):
         obj = {'a': OrderedDict((
             ('b', [{'c': [1, 2]}, 3]),
@@ -164,6 +184,30 @@ def test_pretty_print_with_int_indent(self):
         self.assertEqual(xml, unparse(obj, pretty=True,
                                       newl=newl, indent=indent))
 
+    def test_comment_roundtrip_limited(self):
+        # Input with top-level comments and an element-level comment
+        xml = """
+        <!--top1--><a><b>1</b><!--e1--></a><!--top2-->
+        """
+        # Parse with comment processing enabled
+        parsed1 = parse(xml, process_comments=True)
+        # Unparse and parse again (roundtrip)
+        xml2 = unparse(parsed1)
+        parsed2 = parse(xml2, process_comments=True)
+
+        # Content preserved
+        self.assertIn('a', parsed2)
+        self.assertEqual(parsed2['a']['b'], '1')
+
+        # Element-level comment preserved under '#comment'
+        self.assertEqual(parsed2['a']['#comment'], 'e1')
+
+        # Top-level comments preserved as a list (order not guaranteed)
+        top = parsed2.get('#comment')
+        self.assertIsNotNone(top)
+        top_list = top if isinstance(top, list) else [top]
+        self.assertEqual(set(top_list), {'top1', 'top2'})
+
     def test_encoding(self):
         try:
             value = unichr(39321)

xmltodict.py

@@ -2,7 +2,7 @@
 "Makes working with XML feel like you are working with JSON"
 
 from xml.parsers import expat
-from xml.sax.saxutils import XMLGenerator
+from xml.sax.saxutils import XMLGenerator, escape
 from xml.sax.xmlreader import AttributesImpl
 from io import StringIO
 
@@ -459,7 +459,25 @@ def _emit(key, value, content_handler,
           namespace_separator=':',
           namespaces=None,
           full_document=True,
-          expand_iter=None):
+          expand_iter=None,
+          comment_key='#comment'):
+    if isinstance(key, str) and key == comment_key:
+        comments_list = value if isinstance(value, list) else [value]
+        if isinstance(indent, int):
+            indent = " " * indent
+        for comment_text in comments_list:
+            if comment_text is None:
+                continue
+            comment_text = _convert_value_to_string(comment_text)
+            if comment_text == "":
+                continue
+            if pretty:
+                content_handler.ignorableWhitespace(depth * indent)
+            content_handler.comment(comment_text)
+            if pretty:
+                content_handler.ignorableWhitespace(newl)
+        return
+
     key = _process_namespace(key, namespaces, namespace_separator, attr_prefix)
     if preprocessor is not None:
         result = preprocessor(key, value)
@@ -519,7 +537,7 @@ def _emit(key, value, content_handler,
                   attr_prefix, cdata_key, depth+1, preprocessor,
                   pretty, newl, indent, namespaces=namespaces,
                   namespace_separator=namespace_separator,
-                  expand_iter=expand_iter)
+                  expand_iter=expand_iter, comment_key=comment_key)
         if cdata is not None:
             content_handler.characters(cdata)
         if pretty and children:
@@ -529,8 +547,13 @@ def _emit(key, value, content_handler,
             content_handler.ignorableWhitespace(newl)
 
 
+class _XMLGenerator(XMLGenerator):
+    def comment(self, text):
+        self._write(f"<!--{escape(text)}-->")
+
+
 def unparse(input_dict, output=None, encoding='utf-8', full_document=True,
-            short_empty_elements=False,
+            short_empty_elements=False, comment_key='#comment',
             **kwargs):
     """Emit an XML document for the given `input_dict` (reverse of `parse`).
 
@@ -546,21 +569,25 @@ def unparse(input_dict, output=None, encoding='utf-8', full_document=True,
     can be customized with the `newl` and `indent` parameters.
 
     """
-    if full_document and len(input_dict) != 1:
-        raise ValueError('Document must have exactly one root.')
     must_return = False
     if output is None:
         output = StringIO()
         must_return = True
     if short_empty_elements:
-        content_handler = XMLGenerator(output, encoding, True)
+        content_handler = _XMLGenerator(output, encoding, True)
     else:
-        content_handler = XMLGenerator(output, encoding)
+        content_handler = _XMLGenerator(output, encoding)
     if full_document:
         content_handler.startDocument()
+    seen_root = False
     for key, value in input_dict.items():
-        _emit(key, value, content_handler, full_document=full_document,
-              **kwargs)
+        if key != comment_key and full_document and seen_root:
+            raise ValueError("Document must have exactly one root.")
+        _emit(key, value, content_handler, full_document=full_document, comment_key=comment_key, **kwargs)
+        if key != comment_key:
+            seen_root = True
+    if full_document and not seen_root:
+        raise ValueError("Document must have exactly one root.")
     if full_document:
         content_handler.endDocument()
     if must_return: