[Docutils-checkins] SF.net SVN: docutils:[9239] trunk/docutils

[<mi...@us...>]

Revision: 9239
          http://sourceforge.net/p/docutils/code/9239
Author:   milde
Date:     2022-11-13 16:14:59 +0000 (Sun, 13 Nov 2022)
Log Message:
-----------
New function utils.xml_declaration()

Return XML text declaration.
Include an encoding declaration if the intended encoding is known.

Used in XML (and soon also in HTML) writer.

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/docutils/utils/__init__.py
    trunk/docutils/docutils/writers/docutils_xml.py
    trunk/docutils/test/test_utils.py

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2022-11-11 12:27:01 UTC (rev 9238)
+++ trunk/docutils/HISTORY.txt	2022-11-13 16:14:59 UTC (rev 9239)
@@ -48,6 +48,10 @@
   - Fix previous_sibling() method that led to invalid HTML in some cases
     (cf. patch #195).
 
+* docutils/docutils/utils/__init__.py
+
+  - New utility function `xml_declaration()`.
+
 * docutils/writers/latex2e/__init__.py
 
   - Do not insert ``\usepackage[utf8]{inputenc}`` into UTF-8 encoded

Modified: trunk/docutils/docutils/utils/__init__.py
===================================================================
--- trunk/docutils/docutils/utils/__init__.py	2022-11-11 12:27:01 UTC (rev 9238)
+++ trunk/docutils/docutils/utils/__init__.py	2022-11-13 16:14:59 UTC (rev 9239)
@@ -711,6 +711,19 @@
     return taglist
 
 
+def xml_declaration(encoding=None):
+    """Return an XML text declaration.
+
+    Include an encoding declaration, if `encoding`
+    is not 'unicode', '', or None.
+    """
+    if encoding and encoding.lower() != 'unicode':
+        encoding_declaration = f' encoding="{encoding}"'
+    else:
+        encoding_declaration = ''
+    return f'<?xml version="1.0"{encoding_declaration}?>\n'
+
+
 class DependencyList:
 
     """

Modified: trunk/docutils/docutils/writers/docutils_xml.py
===================================================================
--- trunk/docutils/docutils/writers/docutils_xml.py	2022-11-11 12:27:01 UTC (rev 9238)
+++ trunk/docutils/docutils/writers/docutils_xml.py	2022-11-13 16:14:59 UTC (rev 9239)
@@ -14,7 +14,7 @@
 import xml.sax.saxutils
 
 import docutils
-from docutils import frontend, writers, nodes
+from docutils import frontend, nodes, writers, utils
 
 
 class RawXmlError(docutils.ApplicationError):
@@ -64,7 +64,6 @@
 
 class XMLTranslator(nodes.GenericNodeVisitor):
 
-    xml_declaration = '<?xml version="1.0" encoding="%s"?>\n'
     # TODO: add stylesheet options similar to HTML and LaTeX writers?
     # xml_stylesheet = '<?xml-stylesheet type="text/xsl" href="%s"?>\n'
     doctype = (
@@ -100,8 +99,7 @@
         # Output
         self.output = []
         if settings.xml_declaration:
-            self.output.append(
-                self.xml_declaration % _encoding(settings))
+            self.output.append(utils.xml_declaration(settings.output_encoding))
         if settings.doctype_declaration:
             self.output.append(self.doctype)
         self.output.append(self.generator % docutils.__version__)
@@ -186,10 +184,3 @@
 
     def setDocumentLocator(self, locator):
         self.locator = locator
-
-
-def _encoding(settings):
-    """TEMPORARY, remove in Docutils 0.21"""
-    if settings.output_encoding == 'unicode':
-        return 'utf-8'
-    return settings.output_encoding

Modified: trunk/docutils/test/test_utils.py
===================================================================
--- trunk/docutils/test/test_utils.py	2022-11-11 12:27:01 UTC (rev 9238)
+++ trunk/docutils/test/test_utils.py	2022-11-13 16:14:59 UTC (rev 9239)
@@ -269,6 +269,24 @@
                          ['grc-ibycus-x-altquot', 'grc-ibycus',
                           'grc-x-altquot', 'grc'])
 
+    def test_xml_declaration(self):
+        # default is no encoding declaration
+        self.assertEqual(utils.xml_declaration(), '<?xml version="1.0"?>\n')
+        # if an encoding is passed, declare it
+        self.assertEqual(utils.xml_declaration('ISO-8859-2'),
+                         '<?xml version="1.0" encoding="ISO-8859-2"?>\n')
+        # ignore pseudo encoding name "unicode" introduced by
+        # `docutils.io.Output.encode()`
+        self.assertEqual(utils.xml_declaration('Unicode'),
+                         '<?xml version="1.0"?>\n')
+        # ... non-regarding case
+        self.assertEqual(utils.xml_declaration('UNICODE'),
+                         '<?xml version="1.0"?>\n')
+        # allow %s for later interpolation
+        # (used for part 'html_prolog', cf. docs/api/publisher.html)
+        self.assertEqual(utils.xml_declaration('%s'),
+                         '<?xml version="1.0" encoding="%s"?>\n')
+
     def test_column_width(self):
         self.assertEqual(utils.column_width('de'), 2)
         self.assertEqual(utils.column_width('dâ'), 2)  # pre-composed

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.