From f96cf911a0dfb5344ab9b298c87af76ff3006e33 Mon Sep 17 00:00:00 2001 From: Eli Bendersky Date: Sun, 15 Jul 2012 06:19:44 +0300 Subject: Issue #9458: clarify the documentation of ElementTree.write with regards to the type of the stream expected for a given encoding --- Doc/library/xml.etree.elementtree.rst | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 3c2ddd3..782ebe7 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -650,15 +650,25 @@ ElementTree Objects section root element. - .. method:: write(file, encoding="us-ascii", xml_declaration=None, method="xml") + .. method:: write(file, encoding="us-ascii", xml_declaration=None, \ + method="xml") 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 encoding - (default is US-ASCII). Use ``encoding="unicode"`` to write a Unicode string. - *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). *method* is - either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + :term:`file object` opened for writing. *encoding* [1]_ is the output + encoding (default is US-ASCII). + *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``). + *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is + ``"xml"``). + + The output is either a string (:class:`str`) or binary (:class:`bytes`). + This is controlled by the *encoding* argument. If *encoding* is + ``"unicode"``, the output is a string; otherwise, it's binary. Note that + this may conflict with the type of *file* if it's an open + :term:`file object`; make sure you do not try to write a string to a + binary stream and vice versa. + This is the XML file that is going to be manipulated:: -- cgit v0.12