Index: Doc/library/xml.etree.elementtree.rst
===================================================================
--- Doc/library/xml.etree.elementtree.rst (revision 78956)
+++ Doc/library/xml.etree.elementtree.rst (working copy)
@@ -148,20 +148,22 @@
arguments. Returns an element instance.
-.. function:: tostring(element, encoding=None, method="xml")
+.. function:: tostring(element, encoding="us-ascii", method="xml")
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 None). *method* is either ``"xml"``,
+ the output encoding (default is US-ASCII). Use ``encoding=False`` to
+ generate a Unicode string. *method* is either ``"xml"``,
``"html"`` or ``"text"`` (default is ``"xml"``). Returns an (optionally)
encoded string containing the XML data.
-.. function:: tostringlist(element, encoding=None, method="xml")
+.. function:: tostringlist(element, encoding="us-ascii", method="xml")
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 None). *method* is either ``"xml"``,
+ the output encoding (default is US-ASCII). Use ``encoding=False`` to
+ generate a Unicode string. *method* is either ``"xml"``,
``"html"`` or ``"text"`` (default is ``"xml"``). Returns a list of
(optionally) encoded strings containing the XML data. It does not guarantee
any specific sequence, except that ``"".join(tostringlist(element)) ==
@@ -430,6 +432,7 @@
.. method:: getroot()
+
Returns the root element for this tree.
@@ -457,11 +460,12 @@
root element.
- .. method:: write(file, encoding=None, 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
file object opened for writing. *encoding* [1]_ is the output encoding
- (default is None). *xml_declaration* controls if an XML declaration
+ (default is US-ASCII). Use ``encoding=False`` 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 (default is None). *method* is either
``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). Returns an
Index: Lib/test/test_xml_etree.py
===================================================================
--- Lib/test/test_xml_etree.py (revision 78956)
+++ Lib/test/test_xml_etree.py (working copy)
@@ -65,14 +65,14 @@
if not hasattr(method, '__call__'):
print(method, "not callable")
-def serialize(elem, to_string=True, **options):
+def serialize(elem, to_string=True, encoding=False, **options):
import io
- if options.get("encoding"):
+ if encoding is not False:
file = io.BytesIO()
else:
file = io.StringIO()
tree = ET.ElementTree(elem)
- tree.write(file, **options)
+ tree.write(file, encoding=encoding, **options)
if to_string:
return file.getvalue()
else:
@@ -531,7 +531,7 @@
>>> elem.set('testa', 'testval')
>>> elem.set('testb', 'test2')
>>> ET.tostring(elem)
- 'aa'
+ b'aa'
>>> sorted(elem.keys())
['testa', 'testb']
>>> sorted(elem.items())
@@ -541,7 +541,7 @@
>>> elem.attrib['testb'] = 'test1'
>>> elem.attrib['testc'] = 'test2'
>>> ET.tostring(elem)
- 'aa'
+ b'aa'
"""
def makeelement():
@@ -581,7 +581,7 @@
>>> tree = ET.parse(SIMPLE_XMLFILE)
>>> normalize_crlf(tree)
- >>> tree.write(sys.stdout)
+ >>> tree.write(sys.stdout, encoding=False)
text
texttail
@@ -589,7 +589,7 @@
>>> tree = ET.parse(SIMPLE_NS_XMLFILE)
>>> normalize_crlf(tree)
- >>> tree.write(sys.stdout)
+ >>> tree.write(sys.stdout, encoding=False)
text
texttail
@@ -630,17 +630,17 @@
def parseliteral():
"""
>>> element = ET.XML("text")
- >>> ET.ElementTree(element).write(sys.stdout)
+ >>> ET.ElementTree(element).write(sys.stdout, encoding=False)
text
>>> element = ET.fromstring("text")
- >>> ET.ElementTree(element).write(sys.stdout)
+ >>> ET.ElementTree(element).write(sys.stdout, encoding=False)
text
>>> sequence = ["", "text"]
>>> element = ET.fromstringlist(sequence)
>>> print(ET.tostring(element))
- text
- >>> print("".join(ET.tostringlist(element)))
- text
+ b'text'
+ >>> print(b"".join(ET.tostringlist(element)))
+ b'text'
>>> ET.tostring(element, "ascii")
b"\\ntext"
>>> _, ids = ET.XMLID("text")
@@ -869,10 +869,10 @@
"""
>>> elem = ET.XML("text")
>>> ET.tostring(elem)
- 'text'
+ b'text'
>>> elem = ET.fromstring("text")
>>> ET.tostring(elem)
- 'text'
+ b'text'
"""
def check_encoding(encoding):
@@ -1227,14 +1227,14 @@
Test ProcessingInstruction directly
>>> ET.tostring(ET.ProcessingInstruction('test', 'instruction'))
- ''
+ b''
>>> ET.tostring(ET.PI('test', 'instruction'))
- ''
+ b''
Issue #2746
>>> ET.tostring(ET.PI('test', ''))
- '?>'
+ b'?>'
>>> ET.tostring(ET.PI('test', '\xe3'), 'latin1')
b"\\n\\xe3?>"
"""
@@ -1637,11 +1637,11 @@
>>> e = ET.Element('SomeTag', text="def _f():\n return 3\n")
>>> ET.tostring(e)
- ''
+ b''
>>> ET.XML(ET.tostring(e)).get("text")
'def _f():\n return 3\n'
>>> ET.tostring(ET.XML(ET.tostring(e)))
- ''
+ b''
"""
@@ -1692,15 +1692,15 @@
"""
>>> ET.tostring(ET.Element("{http://namespace.invalid/does/not/exist/}title"))
- ''
+ b''
>>> ET.register_namespace("foo", "http://namespace.invalid/does/not/exist/")
>>> ET.tostring(ET.Element("{http://namespace.invalid/does/not/exist/}title"))
- ''
+ b''
And the Dublin Core namespace is in the default list:
>>> ET.tostring(ET.Element("{http://purl.org/dc/elements/1.1/}title"))
- ''
+ b''
"""
@@ -1786,7 +1786,7 @@
'{${stuff}}localname'
>>> t = ET.ElementTree(e)
>>> ET.tostring(e)
- ''
+ b''
"""
Index: Lib/xml/etree/ElementTree.py
===================================================================
--- Lib/xml/etree/ElementTree.py (revision 78956)
+++ Lib/xml/etree/ElementTree.py (working copy)
@@ -792,7 +792,8 @@
# @def write(file, **options)
# @param file A file name, or a file object opened for writing.
# @param **options Options, given as keyword arguments.
- # @keyparam encoding Optional output encoding (default is None).
+ # @keyparam encoding Optional output encoding (default is US-ASCII).
+ # Use False to return a Unicode string.
# @keyparam method Optional output method ("xml", "html", "text" or
# "c14n"; default is "xml").
# @keyparam xml_declaration Controls if an XML declaration should
@@ -811,6 +812,13 @@
elif method not in _serialize:
# FIXME: raise an ImportError for c14n if ElementC14N is missing?
raise ValueError("unknown method %r" % method)
+ if encoding in (None, True):
+ if method == "c14n":
+ encoding = "utf-8"
+ else:
+ encoding = "us-ascii"
+ elif encoding == str: # lxml.etree compatibility.
+ encoding = False
if hasattr(file_or_filename, "write"):
file = file_or_filename
else:
@@ -827,20 +835,14 @@
_raise_serialization_error(text)
else:
write = file.write
- if not encoding:
- if method == "c14n":
- encoding = "utf-8"
- else:
- encoding = None
- elif xml_declaration or (xml_declaration is None and
- encoding not in ("utf-8", "us-ascii")):
- if method == "xml":
- encoding_ = encoding
- if not encoding:
- # Retrieve the default encoding for the xml declaration
- import locale
- encoding_ = locale.getpreferredencoding()
- write("\n" % encoding_)
+ if method == "xml" and (xml_declaration or (xml_declaration is None and
+ encoding and encoding not in ("utf-8", "us-ascii"))):
+ declared_encoding = encoding
+ if not encoding:
+ # Retrieve the default encoding for the xml declaration
+ import locale
+ declared_encoding = locale.getpreferredencoding()
+ write("\n" % declared_encoding)
if method == "text":
_serialize_text(write, self._root)
else:
@@ -1131,7 +1133,8 @@
# otherwise it is a bytes array.
#
# @param element An Element instance.
-# @keyparam encoding Optional output encoding (default is None).
+# @keyparam encoding Optional output encoding (default is US-ASCII).
+# Use False to return a Unicode string.
# @keyparam method Optional output method ("xml", "html", "text" or
# "c14n"; default is "xml").
# @return An (optionally) encoded string containing the XML data.
@@ -1144,6 +1147,10 @@
file = dummy()
file.write = data.append
ElementTree(element).write(file, encoding, method=method)
+ if encoding is None:
+ encoding = True
+ elif encoding == str: # lxml.etree compatibility.
+ encoding = False
if encoding:
return b"".join(data)
else:
@@ -1155,6 +1162,7 @@
#
# @param element An Element instance.
# @keyparam encoding Optional output encoding (default is US-ASCII).
+# Use False to return a Unicode string.
# @keyparam method Optional output method ("xml", "html", "text" or
# "c14n"; default is "xml").
# @return A sequence object containing the XML data.
@@ -1184,7 +1192,7 @@
# debugging
if not isinstance(elem, ElementTree):
elem = ElementTree(elem)
- elem.write(sys.stdout)
+ elem.write(sys.stdout, encoding=False)
tail = elem.getroot().tail
if not tail or tail[-1] != "\n":
sys.stdout.write("\n")