Close #14377: Add a new parameter to ElementTree.write and some module-level
serialization functions - short_empty_elements. It controls how elements
without contents are emitted.
Patch by Serhiy Storchaka. Feature initially proposed by Ariel Poliak.
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 26f1fbe..267ab07 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -428,29 +428,39 @@
arguments. Returns an element instance.
-.. function:: tostring(element, encoding="us-ascii", method="xml")
+.. function:: tostring(element, encoding="us-ascii", method="xml", *, \
+ short_empty_elements=True)
Generates a string representation of an XML element, including all
subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is
the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to
generate a Unicode string (otherwise, a bytestring is generated). *method*
is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``).
+ *short_empty_elements* has the same meaning as in :meth:`ElementTree.write`.
Returns an (optionally) encoded string containing the XML data.
+ .. versionadded:: 3.4
+ The *short_empty_elements* parameter.
-.. function:: tostringlist(element, encoding="us-ascii", method="xml")
+
+.. function:: tostringlist(element, encoding="us-ascii", method="xml", *, \
+ short_empty_elements=True)
Generates a string representation of an XML element, including all
subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is
the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to
generate a Unicode string (otherwise, a bytestring is generated). *method*
is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``).
+ *short_empty_elements* has the same meaning as in :meth:`ElementTree.write`.
Returns a list of (optionally) encoded strings containing the XML data.
It does not guarantee any specific sequence, except that
``"".join(tostringlist(element)) == tostring(element)``.
.. versionadded:: 3.2
+ .. versionadded:: 3.4
+ The *short_empty_elements* parameter.
+
.. function:: XML(text, parser=None)
@@ -742,7 +752,7 @@
.. method:: write(file, encoding="us-ascii", xml_declaration=None, \
- method="xml")
+ method="xml", *, short_empty_elements=True)
Writes the element tree to a file, as XML. *file* is a file name, or a
:term:`file object` opened for writing. *encoding* [1]_ is the output
@@ -752,6 +762,10 @@
for only if not US-ASCII or UTF-8 or Unicode (default is ``None``).
*method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is
``"xml"``).
+ The keyword-only *short_empty_elements* parameter controls the formatting
+ of elements that contain no content. If *True* (the default), they are
+ emitted as a single self-closed tag, otherwise they are emitted as a pair
+ of start/end tags.
The output is either a string (:class:`str`) or binary (:class:`bytes`).
This is controlled by the *encoding* argument. If *encoding* is
@@ -760,6 +774,9 @@
:term:`file object`; make sure you do not try to write a string to a
binary stream and vice versa.
+ .. versionadded:: 3.4
+ The *short_empty_elements* parameter.
+
This is the XML file that is going to be manipulated::