diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 7948b2ed78f4d0..eedaa5845e15c7 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -710,15 +710,16 @@ Functions .. function:: tostring(element, encoding="us-ascii", method="xml", *, \ xml_declaration=None, default_namespace=None, \ - short_empty_elements=True, standalone=None) + validate=False, short_empty_elements=True, \ + standalone=None) 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"``). - *xml_declaration*, *default_namespace*, *short_empty_elements* and - *standalone* has the same meaning as in :meth:`ElementTree.write`. + *xml_declaration*, *default_namespace*, *validate*, *short_empty_elements* + and *standalone* have the same meaning as in :meth:`ElementTree.write`. Returns an (optionally) encoded string containing the XML data. .. versionchanged:: 3.4 @@ -734,18 +735,22 @@ Functions .. versionchanged:: next Added the *standalone* parameter. + .. versionchanged:: next + Added the *validate* parameter. + .. function:: tostringlist(element, encoding="us-ascii", method="xml", *, \ xml_declaration=None, default_namespace=None, \ - short_empty_elements=True, standalone=None) + validate=False, short_empty_elements=True, \ + standalone=None) 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"``). - *xml_declaration*, *default_namespace*, *short_empty_elements* and - *standalone* has the same meaning as in :meth:`ElementTree.write`. + *xml_declaration*, *default_namespace*, *validate*, *short_empty_elements* + and *standalone* have 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 ``b"".join(tostringlist(element)) == tostring(element)``. @@ -765,6 +770,9 @@ Functions .. versionchanged:: next Added the *standalone* parameter. + .. versionchanged:: next + Added the *validate* parameter. + .. function:: XML(text, parser=None) @@ -1201,7 +1209,8 @@ ElementTree Objects .. method:: write(file, encoding="us-ascii", xml_declaration=None, \ default_namespace=None, method="xml", *, \ - short_empty_elements=True, standalone=None) + validate=False, short_empty_elements=True, \ + standalone=None) 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 @@ -1212,6 +1221,15 @@ ElementTree Objects *default_namespace* sets the default XML namespace (for "xmlns"). *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + + If *validate* is true, check that all characters are legal, + that element and attribute names are valid, and that the content + of comments, processing instructions and HTML elements + like ``