Issue #6472: The xml.etree package is updated to ElementTree 1.3. The cElementTree module is updated too.
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index e074d55..3016773 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -26,7 +26,8 @@
* a number of child elements, stored in a Python sequence
-To create an element instance, use the Element or SubElement factory functions.
+To create an element instance, use the :class:`Element` constructor or the
+:func:`SubElement` factory function.
The :class:`ElementTree` class can be used to wrap an element structure, and
convert it from and to XML.
@@ -46,9 +47,10 @@
.. function:: Comment([text])
Comment element factory. This factory function creates a special element that
- will be serialized as an XML comment. The comment string can be either an 8-bit
- ASCII string or a Unicode string. *text* is a string containing the comment
- string. Returns an element instance representing a comment.
+ will be serialized as an XML comment by the standard serializer. The comment
+ string can be either an 8-bit ASCII string or a Unicode string. *text* is a
+ string containing the comment string. Returns an element instance representing
+ a comment.
.. function:: dump(elem)
@@ -62,37 +64,36 @@
*elem* is an element tree or an individual element.
-.. function:: Element(tag[, attrib][, **extra])
-
- Element factory. This function returns an object implementing the standard
- Element interface. The exact class or type of that object is implementation
- dependent, but it will always be compatible with the _ElementInterface class in
- this module.
-
- The element name, attribute names, and attribute values can be either 8-bit
- ASCII strings or Unicode strings. *tag* is the element name. *attrib* is an
- optional dictionary, containing element attributes. *extra* contains additional
- attributes, given as keyword arguments. Returns an element instance.
-
-
.. function:: fromstring(text)
Parses an XML section from a string constant. Same as XML. *text* is a string
containing XML data. Returns an Element instance.
+.. function:: fromstringlist(sequence[, parser])
+
+ Parses an XML document from a sequence of string fragments. *sequence* is a list
+ or other sequence containing XML data fragments. *parser* is an optional parser
+ instance. If not given, the standard :class:`XMLParser` parser is used.
+ Returns an Element instance.
+
+ .. versionadded:: 2.7
+
+
.. function:: iselement(element)
Checks if an object appears to be a valid element object. *element* is an
element instance. Returns a true value if this is an element object.
-.. function:: iterparse(source[, events])
+.. function:: iterparse(source[, events[, parser]])
Parses an XML section into an element tree incrementally, and reports what's
going on to the user. *source* is a filename or file object containing XML data.
*events* is a list of events to report back. If omitted, only "end" events are
- reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs.
+ reported. *parser* is an optional parser instance. If not given, the standard
+ :class:`XMLParser` parser is used. Returns an :term:`iterator`
+ providing ``(event, elem)`` pairs.
.. note::
@@ -109,8 +110,8 @@
Parses an XML section into an element tree. *source* is a filename or file
object containing XML data. *parser* is an optional parser instance. If not
- given, the standard XMLTreeBuilder parser is used. Returns an ElementTree
- instance.
+ given, the standard :class:`XMLParser` parser is used. Returns an
+ :class:`ElementTree` instance.
.. function:: ProcessingInstruction(target[, text])
@@ -121,6 +122,16 @@
an element instance, representing a processing instruction.
+.. function:: register_namespace(prefix, uri)
+
+ Registers a namespace prefix. The registry is global, and any existing mapping
+ for either the given prefix or the namespace URI will be removed. *prefix* is a
+ namespace prefix. *uri* is a namespace uri. Tags and attributes in this namespace
+ will be serialized with the given prefix, if at all possible.
+
+ .. versionadded:: 2.7
+
+
.. function:: SubElement(parent, tag[, attrib[, **extra]])
Subelement factory. This function creates an element instance, and appends it
@@ -140,163 +151,201 @@
US-ASCII). Returns an encoded string containing the XML data.
-.. function:: XML(text)
+.. function:: tostringlist(element[, encoding])
+
+ Generates a string representation of an XML element, including all subelements.
+ *element* is an Element instance. *encoding* is the output encoding (default is
+ US-ASCII). Returns a sequence object containing the XML data.
+
+ .. versionadded:: 2.7
+
+
+.. function:: XML(text[, parser])
Parses an XML section from a string constant. This function can be used to
embed "XML literals" in Python code. *text* is a string containing XML data.
- Returns an Element instance.
+ *parser* is an optional parser instance. If not given, the standard
+ :class:`XMLParser` parser is used. Returns an Element instance.
-.. function:: XMLID(text)
+.. function:: XMLID(text[, parser])
Parses an XML section from a string constant, and also returns a dictionary
which maps from element id:s to elements. *text* is a string containing XML
- data. Returns a tuple containing an Element instance and a dictionary.
+ data. *parser* is an optional parser instance. If not given, the standard
+ :class:`XMLParser` parser is used. Returns a tuple containing an Element
+ instance and a dictionary.
-.. _elementtree-element-interface:
+.. _elementtree-element-objects:
-The Element Interface
----------------------
+Element Objects
+---------------
-Element objects returned by Element or SubElement have the following methods
-and attributes.
+.. class:: Element(tag[, attrib[, **extra]])
-.. attribute:: Element.tag
+ Element class. This class defines the Element interface, and provides a
+ reference implementation of this interface.
- A string identifying what kind of data this element represents (the element
- type, in other words).
+ The element name, attribute names, and attribute values can be either 8-bit
+ ASCII strings or Unicode strings. *tag* is the element name. *attrib* is an
+ optional dictionary, containing element attributes. *extra* contains additional
+ attributes, given as keyword arguments.
-.. attribute:: Element.text
+ .. attribute:: tag
- The *text* attribute can be used to hold additional data associated with the
- element. As the name implies this attribute is usually a string but may be any
- application-specific object. If the element is created from an XML file the
- attribute will contain any text found between the element tags.
+ A string identifying what kind of data this element represents (the element
+ type, in other words).
-.. attribute:: Element.tail
+ .. attribute:: text
- The *tail* attribute can be used to hold additional data associated with the
- element. This attribute is usually a string but may be any application-specific
- object. If the element is created from an XML file the attribute will contain
- any text found after the element's end tag and before the next tag.
+ The *text* attribute can be used to hold additional data associated with the
+ element. As the name implies this attribute is usually a string but may be
+ any application-specific object. If the element is created from an XML file
+ the attribute will contain any text found between the element tags.
-.. attribute:: Element.attrib
+ .. attribute:: tail
- A dictionary containing the element's attributes. Note that while the *attrib*
- value is always a real mutable Python dictionary, an ElementTree implementation
- may choose to use another internal representation, and create the dictionary
- only if someone asks for it. To take advantage of such implementations, use the
- dictionary methods below whenever possible.
+ The *tail* attribute can be used to hold additional data associated with the
+ element. This attribute is usually a string but may be any
+ application-specific object. If the element is created from an XML file the
+ attribute will contain any text found after the element's end tag and before
+ the next tag.
-The following dictionary-like methods work on the element attributes.
+ .. attribute:: attrib
-.. method:: Element.clear()
+ A dictionary containing the element's attributes. Note that while the
+ *attrib* value is always a real mutable Python dictionary, an ElementTree
+ implementation may choose to use another internal representation, and create
+ the dictionary only if someone asks for it. To take advantage of such
+ implementations, use the dictionary methods below whenever possible.
- Resets an element. This function removes all subelements, clears all
- attributes, and sets the text and tail attributes to None.
+ The following dictionary-like methods work on the element attributes.
-.. method:: Element.get(key[, default=None])
+ .. method:: clear()
- Gets the element attribute named *key*.
+ Resets an element. This function removes all subelements, clears all
+ attributes, and sets the text and tail attributes to None.
- Returns the attribute value, or *default* if the attribute was not found.
+ .. method:: get(key[, default])
-.. method:: Element.items()
+ Gets the element attribute named *key*.
- Returns the element attributes as a sequence of (name, value) pairs. The
- attributes are returned in an arbitrary order.
+ Returns the attribute value, or *default* if the attribute was not found.
-.. method:: Element.keys()
+ .. method:: items()
+
+ Returns the element attributes as a sequence of (name, value) pairs. The
+ attributes are returned in an arbitrary order.
+
+
+ .. method:: keys()
+
+ Returns the elements attribute names as a list. The names are returned in an
+ arbitrary order.
+
+
+ .. method:: set(key, value)
+
+ Set the attribute *key* on the element to *value*.
+
+ The following methods work on the element's children (subelements).
+
+
+ .. method:: append(subelement)
- Returns the elements attribute names as a list. The names are returned in an
- arbitrary order.
+ Adds the element *subelement* to the end of this elements internal list of
+ subelements.
-.. method:: Element.set(key, value)
+ .. method:: extend(subelements)
- Set the attribute *key* on the element to *value*.
+ Appends *subelements* from a sequence object with zero or more elements.
+ Raises :exc:`AssertionError` if a subelement is not a valid object.
-The following methods work on the element's children (subelements).
+ .. versionadded:: 2.7
-.. method:: Element.append(subelement)
+ .. method:: find(match)
- Adds the element *subelement* to the end of this elements internal list of
- subelements.
+ Finds the first subelement matching *match*. *match* may be a tag name or path.
+ Returns an element instance or ``None``.
-.. method:: Element.find(match)
+ .. method:: findall(match)
- Finds the first subelement matching *match*. *match* may be a tag name or path.
- Returns an element instance or ``None``.
+ Finds all subelements matching *match*. *match* may be a tag name or path.
+ Returns an iterable yielding all matching elements in document order.
-.. method:: Element.findall(match)
+ .. method:: findtext(condition[, default])
- Finds all subelements matching *match*. *match* may be a tag name or path.
- Returns an iterable yielding all matching elements in document order.
+ Finds text for the first subelement matching *condition*. *condition* may be
+ a tag name or path. Returns the text content of the first matching element,
+ or *default* if no element was found. Note that if the matching element has
+ no text content an empty string is returned.
-.. method:: Element.findtext(condition[, default=None])
+ .. method:: getchildren()
- Finds text for the first subelement matching *condition*. *condition* may be a
- tag name or path. Returns the text content of the first matching element, or
- *default* if no element was found. Note that if the matching element has no
- text content an empty string is returned.
+ .. deprecated:: 2.7
+ Use ``list(elem)`` or iteration.
-.. method:: Element.getchildren()
+ .. method:: getiterator([tag])
- Returns all subelements. The elements are returned in document order.
+ .. deprecated:: 2.7
+ Use method :meth:`Element.iter` instead.
-.. method:: Element.getiterator([tag=None])
+ .. method:: insert(index, element)
- Creates a tree iterator with the current element as the root. The iterator
- iterates over this element and all elements below it, in document (depth first)
- order. If *tag* is not ``None`` or ``'*'``, only elements whose tag equals
- *tag* are returned from the iterator.
+ Inserts a subelement at the given position in this element.
-.. method:: Element.insert(index, element)
+ .. method:: iter([tag])
- Inserts a subelement at the given position in this element.
+ Creates a tree iterator with the current element as the root. The iterator
+ iterates over this element and all elements below it, in document (depth
+ first) order. If *tag* is not ``None`` or ``'*'``, only elements whose tag
+ equals *tag* are returned from the iterator. If the tree structure is
+ modified during iteration, the result is undefined.
-.. method:: Element.makeelement(tag, attrib)
+ .. method:: makeelement(tag, attrib)
- Creates a new element object of the same type as this element. Do not call this
- method, use the SubElement factory function instead.
+ Creates a new element object of the same type as this element. Do not call
+ this method, use the SubElement factory function instead.
-.. method:: Element.remove(subelement)
+ .. method:: remove(subelement)
- Removes *subelement* from the element. Unlike the findXYZ methods this method
- compares elements based on the instance identity, not on tag value or contents.
+ Removes *subelement* from the element. Unlike the findXYZ methods this
+ method compares elements based on the instance identity, not on tag value
+ or contents.
-Element objects also support the following sequence type methods for working
-with subelements: :meth:`__delitem__`, :meth:`__getitem__`, :meth:`__setitem__`,
-:meth:`__len__`.
+ Element objects also support the following sequence type methods for working
+ with subelements: :meth:`__delitem__`, :meth:`__getitem__`, :meth:`__setitem__`,
+ :meth:`__len__`.
-Caution: Because Element objects do not define a :meth:`__nonzero__` method,
-elements with no subelements will test as ``False``. ::
+ Caution: Because Element objects do not define a :meth:`__nonzero__` method,
+ elements with no subelements will test as ``False``. ::
- element = root.find('foo')
+ element = root.find('foo')
- if not element: # careful!
- print "element not found, or element has no subelements"
+ if not element: # careful!
+ print "element not found, or element has no subelements"
- if element is None:
- print "element not found"
+ if element is None:
+ print "element not found"
.. _elementtree-elementtree-objects:
@@ -348,9 +397,8 @@
.. method:: getiterator([tag])
- Creates and returns a tree iterator for the root element. The iterator
- loops over all elements in this tree, in section order. *tag* is the tag
- to look for (default is to return all elements)
+ .. deprecated:: 2.7
+ Use method :meth:`ElementTree.iter` instead.
.. method:: getroot()
@@ -358,19 +406,28 @@
Returns the root element for this tree.
+ .. method:: iter([tag])
+
+ Creates and returns a tree iterator for the root element. The iterator
+ loops over all elements in this tree, in section order. *tag* is the tag
+ to look for (default is to return all elements)
+
+
.. method:: parse(source[, parser])
Loads an external XML section into this element tree. *source* is a file
name or file object. *parser* is an optional parser instance. If not
- given, the standard XMLTreeBuilder parser is used. Returns the section
+ given, the standard XMLParser parser is used. Returns the section
root element.
- .. method:: write(file[, encoding])
+ .. method:: write(file[, encoding[, xml_declaration]])
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 US-ASCII).
+ (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. None is default.
This is the XML file that is going to be manipulated::
@@ -389,13 +446,13 @@
>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
- <Element html at b7d3f1ec>
+ <Element 'html' at b7d3f1ec>
>>> p = tree.find("body/p") # Finds first occurrence of tag p in body
>>> p
- <Element p at 8416e0c>
- >>> links = p.getiterator("a") # Returns list of all links
+ <Element 'p' at 8416e0c>
+ >>> links = list(p.iter("a")) # Returns list of all links
>>> links
- [<Element a at b7d4f9ec>, <Element a at b7d4fb0c>]
+ [<Element 'a' at b7d4f9ec>, <Element 'a' at b7d4fb0c>]
>>> for i in links: # Iterates through all found links
... i.attrib["target"] = "blank"
>>> tree.write("output.xhtml")
@@ -433,7 +490,7 @@
.. method:: close()
- Flushes the parser buffers, and returns the toplevel document
+ Flushes the builder buffers, and returns the toplevel document
element. Returns an Element instance.
@@ -455,18 +512,31 @@
containing element attributes. Returns the opened element.
-.. _elementtree-xmltreebuilder-objects:
+ In addition, a custom :class:`TreeBuilder` object can provide the
+ following method:
-XMLTreeBuilder Objects
-----------------------
+ .. method:: doctype(name, pubid, system)
+
+ Handles a doctype declaration. *name* is the doctype name. *pubid* is the
+ public identifier. *system* is the system identifier. This method does not
+ exist on the default :class:`TreeBuilder` class.
+
+ .. versionadded:: 2.7
-.. class:: XMLTreeBuilder([html,] [target])
+.. _elementtree-xmlparser-objects:
+
+XMLParser Objects
+-----------------
+
+
+.. class:: XMLParser([html [, target[, encoding]]])
Element structure builder for XML source data, based on the expat parser. *html*
are predefined HTML entities. This flag is not supported by the current
implementation. *target* is the target object. If omitted, the builder uses an
- instance of the standard TreeBuilder class.
+ instance of the standard TreeBuilder class. *encoding* [1]_ is optional.
+ If given, the value overrides the encoding specified in the XML file.
.. method:: close()
@@ -476,22 +546,23 @@
.. method:: doctype(name, pubid, system)
- Handles a doctype declaration. *name* is the doctype name. *pubid* is the
- public identifier. *system* is the system identifier.
+ .. deprecated:: 2.7
+ Define the :meth:`TreeBuilder.doctype` method on a custom TreeBuilder
+ target.
.. method:: feed(data)
Feeds data to the parser. *data* is encoded data.
-:meth:`XMLTreeBuilder.feed` calls *target*\'s :meth:`start` method
+:meth:`XMLParser.feed` calls *target*\'s :meth:`start` method
for each opening tag, its :meth:`end` method for each closing tag,
-and data is processed by method :meth:`data`. :meth:`XMLTreeBuilder.close`
+and data is processed by method :meth:`data`. :meth:`XMLParser.close`
calls *target*\'s method :meth:`close`.
-:class:`XMLTreeBuilder` can be used not only for building a tree structure.
+:class:`XMLParser` can be used not only for building a tree structure.
This is an example of counting the maximum depth of an XML file::
- >>> from xml.etree.ElementTree import XMLTreeBuilder
+ >>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth: # The target object of the parser
... maxDepth = 0
... depth = 0
@@ -507,7 +578,7 @@
... return self.maxDepth
...
>>> target = MaxDepth()
- >>> parser = XMLTreeBuilder(target=target)
+ >>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
... <b>
@@ -530,4 +601,3 @@
appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
and http://www.iana.org/assignments/character-sets.
-