Index: Doc/library/xml.etree.elementtree.rst =================================================================== --- Doc/library/xml.etree.elementtree.rst (revision 83346) +++ 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="unicode"`` 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="unicode"`` 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,15 +460,16 @@ 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="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 (default is None). *method* is either - ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). Returns an - (optionally) encoded string. + for only if not US-ASCII or UTF-8 or Unicode (default is None). *method* is + either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + Returns an (optionally) encoded string. This is the XML file that is going to be manipulated:: Index: Lib/xml/etree/ElementTree.py =================================================================== --- Lib/xml/etree/ElementTree.py (revision 83346) +++ Lib/xml/etree/ElementTree.py (working copy) @@ -792,12 +792,13 @@ # @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 "unicode" 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 # be added to the file. Use False for never, True for always, - # None for only if not US-ASCII or UTF-8. None is default. + # None for only if not US-ASCII or UTF-8 or Unicode. None is default. def write(self, file_or_filename, # keyword arguments @@ -811,14 +812,23 @@ elif method not in _serialize: # FIXME: raise an ImportError for c14n if ElementC14N is missing? raise ValueError("unknown method %r" % method) + if not encoding: + if method == "c14n": + encoding = "utf-8" + else: + encoding = "us-ascii" + elif encoding == str: # lxml.etree compatibility. + encoding = "unicode" + else: + encoding = encoding.lower() if hasattr(file_or_filename, "write"): file = file_or_filename else: - if encoding: + if encoding != "unicode": file = open(file_or_filename, "wb") else: file = open(file_or_filename, "w") - if encoding: + if encoding != "unicode": def write(text): try: return file.write(text.encode(encoding, @@ -827,20 +837,15 @@ _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 not in ("utf-8", "us-ascii", "unicode"))): + declared_encoding = encoding + if encoding == "unicode": + # 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: @@ -1127,11 +1132,12 @@ ## # Generates a string representation of an XML element, including all -# subelements. If encoding is None, the return type is a string; +# subelements. If encoding is False, the return type is a string; # 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 "unicode" 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,17 +1150,20 @@ file = dummy() file.write = data.append ElementTree(element).write(file, encoding, method=method) - if encoding: - return b"".join(data) - else: + if encoding in (str, "unicode"): return "".join(data) + else: + return b"".join(data) ## # Generates a string representation of an XML element, including all -# subelements. The string is returned as a sequence of string fragments. +# subelements. If encoding is False, the string is returned as a +# sequence of string fragments; otherwise it is a sequence of +# bytestrings. # # @param element An Element instance. # @keyparam encoding Optional output encoding (default is US-ASCII). +# Use "unicode" 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 +1193,7 @@ # debugging if not isinstance(elem, ElementTree): elem = ElementTree(elem) - elem.write(sys.stdout) + elem.write(sys.stdout, encoding="unicode") tail = elem.getroot().tail if not tail or tail[-1] != "\n": sys.stdout.write("\n") Index: Lib/test/test_xml_etree.py =================================================================== --- Lib/test/test_xml_etree.py (revision 83346) +++ Lib/test/test_xml_etree.py (working copy) @@ -66,14 +66,14 @@ if not hasattr(method, '__call__'): print(method, "not callable") -def serialize(elem, to_string=True, **options): +def serialize(elem, to_string=True, encoding='unicode', **options): import io - if options.get("encoding"): + if encoding != 'unicode': 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: @@ -532,7 +532,7 @@ >>> elem.set('testa', 'testval') >>> elem.set('testb', 'test2') >>> ET.tostring(elem) - 'aa' + b'aa' >>> sorted(elem.keys()) ['testa', 'testb'] >>> sorted(elem.items()) @@ -542,7 +542,7 @@ >>> elem.attrib['testb'] = 'test1' >>> elem.attrib['testc'] = 'test2' >>> ET.tostring(elem) - 'aa' + b'aa' """ def makeelement(): @@ -582,7 +582,7 @@ >>> tree = ET.parse(SIMPLE_XMLFILE) >>> normalize_crlf(tree) - >>> tree.write(sys.stdout) + >>> tree.write(sys.stdout, encoding='unicode') text texttail @@ -590,7 +590,7 @@ >>> tree = ET.parse(SIMPLE_NS_XMLFILE) >>> normalize_crlf(tree) - >>> tree.write(sys.stdout) + >>> tree.write(sys.stdout, encoding='unicode') text texttail @@ -631,17 +631,17 @@ def parseliteral(): """ >>> element = ET.XML("text") - >>> ET.ElementTree(element).write(sys.stdout) + >>> ET.ElementTree(element).write(sys.stdout, encoding='unicode') text >>> element = ET.fromstring("text") - >>> ET.ElementTree(element).write(sys.stdout) + >>> ET.ElementTree(element).write(sys.stdout, encoding='unicode') 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") @@ -870,10 +870,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): @@ -1228,14 +1228,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?>" """ @@ -1638,11 +1638,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'' """ @@ -1693,15 +1693,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'' """ @@ -1787,7 +1787,7 @@ '{${stuff}}localname' >>> t = ET.ElementTree(e) >>> ET.tostring(e) - '' + b'' """