From: Serhiy Storchaka Date: Sun, 13 Jan 2013 20:24:27 +0000 (+0200) Subject: Cleanup the docs ElementTree a bit. X-Git-Tag: v3.4.0a1~1613 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9e189f0a28ed99a29915dda839b913109a178111;p=python Cleanup the docs ElementTree a bit. --- 9e189f0a28ed99a29915dda839b913109a178111 diff --cc Doc/library/xml.etree.elementtree.rst index 88855d952f,144e344397..2a9f9b30b0 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@@ -428,23 -428,17 +428,23 @@@ Function arguments. Returns an element instance. - .. function:: tostring(element, encoding="us-ascii", method="xml", *,\ -.. 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", *,\ ++.. 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 @@@ -751,9 -741,8 +751,9 @@@ ElementTree Object section root element. - .. method:: write(file, encoding="us-ascii", xml_declaration=None,\ - default_namespace=None, method="xml", *,\ + .. method:: write(file, encoding="us-ascii", xml_declaration=None, \ - default_namespace=None, method="xml") ++ default_namespace=None, 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 @@@ -761,13 -750,9 +761,13 @@@ *xml_declaration* controls if an XML declaration should be added to the file. Use ``False`` for never, ``True`` for always, ``None`` for only if not US-ASCII or UTF-8 or Unicode (default is ``None``). + *default_namespace* sets the default XML namespace (for "xmlns"). *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is - ``"xml"``). *default_namespace* sets the default XML namespace (for - "xmlns"). + ``"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 diff --cc Lib/xml/etree/ElementTree.py index eab0a4fa3f,e8e309c3a0..85cab2b17b --- a/Lib/xml/etree/ElementTree.py +++ b/Lib/xml/etree/ElementTree.py @@@ -783,22 -800,7 +783,22 @@@ class ElementTree encoding=None, xml_declaration=None, default_namespace=None, - method=None): + method=None, *, + short_empty_elements=True): - """Write the element tree to a file, as XML. 'file_or_filename' is a - file name or a file object opened for writing. 'encoding' is the - output encoding (default is US-ASCII). 'xml_declaration' controls - if an XML declaration should be added to the output. Use False - for never, True for always, None for only if not US-ASCII or - UTF-8 or Unicode (default is None). 'method' is either "xml" - (default), "html", "text" or "c14n". ++ """Write the element tree to a file, as XML. 'file_or_filename' is a ++ file name or a file object opened for writing. ++ 'encoding' is the output encoding (default is US-ASCII). ++ 'xml_declaration' controls if an XML declaration should be added ++ to the output. Use False for never, True for always, None for only ++ if not US-ASCII or UTF-8 or Unicode (default is None). + 'default_namespace' sets the default XML namespace (for "xmlns"). ++ 'method' is either "xml" (default), "html", "text" or "c14n". + The keyword-only 'short_empty_elements' parameter controls the - formatting of elements that contain no content. If True (default), ++ formatting of elements that contain no content. If True (default), + they are emitted as a single self-closed tag, otherwise they are + emitted as a pair of start/end tags. + + """ if not method: method = "xml" elif method not in _serialize: