summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorEli Bendersky <eliben@gmail.com>2012-07-15 03:19:44 (GMT)
committerEli Bendersky <eliben@gmail.com>2012-07-15 03:19:44 (GMT)
commitf96cf911a0dfb5344ab9b298c87af76ff3006e33 (patch)
tree4522e2c91a6327fdb27a2c6c51ad03620a57be08 /Doc/library
parent00f402bfcbe3245f9c62f86376fc77bb9e7de639 (diff)
downloadcpython-f96cf911a0dfb5344ab9b298c87af76ff3006e33.zip
cpython-f96cf911a0dfb5344ab9b298c87af76ff3006e33.tar.gz
cpython-f96cf911a0dfb5344ab9b298c87af76ff3006e33.tar.bz2
Issue #9458: clarify the documentation of ElementTree.write with regards to the type of the stream expected for a given encoding
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/xml.etree.elementtree.rst24
1 files 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::