diff options
Diffstat (limited to 'Doc/library/xml.etree.elementtree.rst')
| -rw-r--r-- | Doc/library/xml.etree.elementtree.rst | 520 |
1 files changed, 318 insertions, 202 deletions
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index bc04a53..18c35aa 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -5,10 +5,13 @@ :synopsis: Implementation of the ElementTree API. .. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com> +**Source code:** :source:`Lib/xml/etree/ElementTree.py` -The Element type is a flexible container object, designed to store hierarchical -data structures in memory. The type can be described as a cross between a list -and a dictionary. +-------------- + +The :class:`Element` type is a flexible container object, designed to store +hierarchical data structures in memory. The type can be described as a cross +between a list and a dictionary. Each element has a number of properties associated with it: @@ -23,7 +26,8 @@ Each element has a number of properties associated with it: * 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. @@ -31,8 +35,14 @@ convert it from and to XML. A C implementation of this API is available as :mod:`xml.etree.cElementTree`. See http://effbot.org/zone/element-index.htm for tutorials and links to other -docs. Fredrik Lundh's page is also the location of the development version of the -xml.etree.ElementTree. +docs. Fredrik Lundh's page is also the location of the development version of +the xml.etree.ElementTree. + +.. versionchanged:: 3.2 + The ElementTree API is updated to 1.3. For more information, see + `Introducing ElementTree 1.3 + <http://effbot.org/zone/elementtree-13-intro.htm>`_. + .. _elementtree-functions: @@ -43,16 +53,16 @@ Functions .. function:: Comment(text=None) 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 ASCII-only :class:`bytes` object or a :class:`str` object. *text* is a - string containing the comment string. Returns an element instance + that will be serialized as an XML comment by the standard serializer. The + comment string can be either a bytestring or a Unicode string. *text* is a + string containing the comment string. Returns an element instance representing a comment. .. function:: dump(elem) - Writes an element tree or element structure to sys.stdout. This function should - be used for debugging only. + Writes an element tree or element structure to sys.stdout. This function + should be used for debugging only. The exact output format is implementation dependent. In this version, it's written as an ordinary XML file. @@ -60,39 +70,36 @@ Functions *elem* is an element tree or an individual element. -.. function:: Element(tag, attrib={}, **extra) +.. function:: fromstring(text) - 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. + Parses an XML section from a string constant. Same as :func:`XML`. *text* + is a string containing XML data. Returns an :class:`Element` instance. - The element name, attribute names, and attribute values can be either an - ASCII-only :class:`bytes` object or a :class:`str` object. *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:: fromstringlist(sequence, parser=None) -.. function:: fromstring(text) + 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 :class:`Element` instance. - Parses an XML section from a string constant. Same as XML. *text* is a string - containing XML data. Returns an Element instance. + .. versionadded:: 3.2 .. 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. + 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=None) +.. function:: iterparse(source, events=None, parser=None) Parses an XML section into an element tree incrementally, and reports what's going on to the user. *source* is a filename or :term:`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. + events are 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:: @@ -107,196 +114,271 @@ Functions .. function:: parse(source, parser=None) - 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. + 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 :class:`XMLParser` parser is used. Returns an + :class:`ElementTree` instance. .. function:: ProcessingInstruction(target, text=None) - PI element factory. This factory function creates a special element that will - be serialized as an XML processing instruction. *target* is a string containing - the PI target. *text* is a string containing the PI contents, if given. Returns - an element instance, representing a processing instruction. + PI element factory. This factory function creates a special element that + will be serialized as an XML processing instruction. *target* is a string + containing the PI target. *text* is a string containing the PI contents, if + given. Returns 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:: 3.2 .. function:: SubElement(parent, tag, attrib={}, **extra) - Subelement factory. This function creates an element instance, and appends it - to an existing element. + Subelement factory. This function creates an element instance, and appends + it to an existing element. + + The element name, attribute names, and attribute values can be either + bytestrings or Unicode strings. *parent* is the parent element. *tag* is + the subelement name. *attrib* is an optional dictionary, containing element + attributes. *extra* contains additional attributes, given as keyword + arguments. Returns an element instance. + + +.. 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 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. - The element name, attribute names, and attribute values can be an ASCII-only - :class:`bytes` object or a :class:`str` object. *parent* is the parent - element. *tag* is the subelement name. *attrib* is an optional dictionary, - containing element attributes. *extra* contains additional attributes, given - as keyword arguments. Returns an element instance. +.. function:: tostringlist(element, encoding="us-ascii", method="xml") -.. function:: tostring(element, encoding=None) + 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 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)) == + tostring(element)``. - 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 an encoded string containing the XML data. + .. versionadded:: 3.2 -.. function:: XML(text) +.. function:: XML(text, parser=None) 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. + embed "XML literals" in Python code. *text* is a string containing XML + data. *parser* is an optional parser instance. If not given, the standard + :class:`XMLParser` parser is used. Returns an :class:`Element` instance. -.. function:: XMLID(text) +.. function:: XMLID(text, parser=None) 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. + which maps from element id:s to elements. *text* is a string containing XML + data. *parser* is an optional parser instance. If not given, the standard + :class:`XMLParser` parser is used. Returns a tuple containing an + :class:`Element` instance and a dictionary. + + +.. _elementtree-element-objects: + +Element Objects +--------------- + + +.. class:: Element(tag, attrib={}, **extra) + + Element class. This class defines the Element interface, and provides a + reference implementation of this interface. + + The element name, attribute names, and attribute values can be either + bytestrings 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:: tag + + A string identifying what kind of data this element represents (the + element type, in other words). + + + .. attribute:: text + 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. -.. _elementtree-element-interface: -The Element Interface ---------------------- + .. attribute:: tail -Element objects returned by Element or SubElement have the following methods -and attributes. + 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. -.. attribute:: Element.tag + .. attribute:: attrib - A string identifying what kind of data this element represents (the element - type, in other words). + 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 following dictionary-like methods work on the element attributes. -.. attribute:: Element.text - 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. + .. method:: clear() + Resets an element. This function removes all subelements, clears all + attributes, and sets the text and tail attributes to None. -.. attribute:: Element.tail - 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. + .. method:: get(key, default=None) + Gets the element attribute named *key*. -.. attribute:: Element.attrib + Returns the attribute value, or *default* if the attribute was not found. - 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 following dictionary-like methods work on the element attributes. + .. method:: items() + Returns the element attributes as a sequence of (name, value) pairs. The + attributes are returned in an arbitrary order. -.. method:: Element.clear() - Resets an element. This function removes all subelements, clears all - attributes, and sets the text and tail attributes to None. + .. method:: keys() + Returns the elements attribute names as a list. The names are returned + in an arbitrary order. -.. method:: Element.get(key, default=None) - Gets the element attribute named *key*. + .. method:: set(key, value) - Returns the attribute value, or *default* if the attribute was not found. + Set the attribute *key* on the element to *value*. + The following methods work on the element's children (subelements). -.. method:: Element.items() - Returns the element attributes as a sequence of (name, value) pairs. The - attributes are returned in an arbitrary order. + .. method:: append(subelement) + Adds the element *subelement* to the end of this elements internal list + of subelements. -.. method:: Element.keys() - Returns the elements attribute names as a list. The names are returned in an - arbitrary order. + .. method:: extend(subelements) + Appends *subelements* from a sequence object with zero or more elements. + Raises :exc:`AssertionError` if a subelement is not a valid object. -.. method:: Element.set(key, value) + .. versionadded:: 3.2 - Set the attribute *key* on the element to *value*. -The following methods work on the element's children (subelements). + .. method:: find(match) + Finds the first subelement matching *match*. *match* may be a tag name + or path. Returns an element instance or ``None``. -.. method:: Element.append(subelement) - Adds the element *subelement* to the end of this elements internal list of - subelements. + .. method:: findall(match) + Finds all matching subelements, by tag name or path. Returns a list + containing all matching elements in document order. -.. method:: Element.find(match) - Finds the first subelement matching *match*. *match* may be a tag name or path. - Returns an element instance or ``None``. + .. method:: findtext(match, default=None) + Finds text for the first subelement matching *match*. *match* 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.findall(match) - Finds all subelements matching *match*. *match* may be a tag name or path. - Returns an iterable yielding all matching elements in document order. + .. method:: getchildren() + .. deprecated:: 3.2 + Use ``list(elem)`` or iteration. -.. method:: Element.findtext(condition, default=None) - 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:: getiterator(tag=None) + + .. deprecated:: 3.2 + Use method :meth:`Element.iter` instead. + + + .. method:: insert(index, element) + + Inserts a subelement at the given position in this element. + + + .. method:: iter(tag=None) + Creates a tree :term:`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.getchildren() - Returns all subelements. The elements are returned in document order. + .. method:: iterfind(match) + Finds all matching subelements, by tag name or path. Returns an iterable + yielding all matching elements in document order. -.. method:: Element.getiterator(tag=None) + .. versionadded:: 3.2 - 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. + .. method:: itertext() -.. method:: Element.insert(index, element) + Creates a text iterator. The iterator loops over this element and all + subelements, in document order, and returns all inner text. - Inserts a subelement at the given position in this element. + .. versionadded:: 3.2 -.. 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 :func:`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 find\* 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__`. + :class:`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:`__bool__` method, -elements with no subelements will test as ``False``. :: + Caution: Elements with no subelements will test as ``False``. This behavior + will change in future versions. Use specific ``len(elem)`` or ``elem is + None`` test instead. :: - 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: @@ -307,50 +389,49 @@ ElementTree Objects .. class:: ElementTree(element=None, file=None) - ElementTree wrapper class. This class represents an entire element hierarchy, - and adds some extra support for serialization to and from standard XML. + ElementTree wrapper class. This class represents an entire element + hierarchy, and adds some extra support for serialization to and from + standard XML. - *element* is the root element. The tree is initialized with the contents of the - XML *file* if given. + *element* is the root element. The tree is initialized with the contents + of the XML *file* if given. .. method:: _setroot(element) Replaces the root element for this tree. This discards the current contents of the tree, and replaces it with the given element. Use with - care. *element* is an element instance. + care. *element* is an element instance. - .. method:: find(path) + .. method:: find(match) - Finds the first toplevel element with given tag. Same as - getroot().find(path). *path* is the element to look for. Returns the - first matching element, or ``None`` if no element was found. + Finds the first toplevel element matching *match*. *match* may be a tag + name or path. Same as getroot().find(match). Returns the first matching + element, or ``None`` if no element was found. - .. method:: findall(path) + .. method:: findall(match) - Finds all toplevel elements with the given tag. Same as - getroot().findall(path). *path* is the element to look for. Returns a - list or :term:`iterator` containing all matching elements, in document - order. + Finds all matching subelements, by tag name or path. Same as + getroot().findall(match). *match* may be a tag name or path. Returns a + list containing all matching elements, in document order. - .. method:: findtext(path, default=None) + .. method:: findtext(match, default=None) Finds the element text for the first toplevel element with given tag. - Same as getroot().findtext(path). *path* is the toplevel element to look - for. *default* is the value to return if the element was not - found. Returns the text content of the first matching element, or the - default value no element was found. Note that if the element has is - found, but has no text content, this method returns an empty string. + Same as getroot().findtext(match). *match* may be a tag name or path. + *default* is the value to return if the element was not found. Returns + the text content of the first matching element, or the default value no + element was found. Note that if the element is found, but has no text + content, this method returns an empty string. .. method:: getiterator(tag=None) - 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:: 3.2 + Use method :meth:`ElementTree.iter` instead. .. method:: getroot() @@ -358,19 +439,40 @@ ElementTree Objects Returns the root element for this tree. + .. method:: iter(tag=None) + + 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:: iterfind(match) + + Finds all matching subelements, by tag name or path. Same as + getroot().iterfind(match). Returns an iterable yielding all matching + elements in document order. + + .. versionadded:: 3.2 + + .. method:: parse(source, parser=None) Loads an external XML section into this element tree. *source* is a file name or :term:`file object`. *parser* is an optional parser instance. - If not given, the standard XMLTreeBuilder parser is used. Returns the section + If not given, the standard XMLParser parser is used. Returns the section root element. - .. method:: write(file, encoding=None) + .. 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). + (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"``). + Returns an (optionally) encoded string. This is the XML file that is going to be manipulated:: @@ -389,13 +491,13 @@ Example of changing the attribute "target" of every link in first paragraph:: >>> from xml.etree.ElementTree import ElementTree >>> tree = ElementTree() >>> tree.parse("index.xhtml") - <Element html at b7d3f1ec> + <Element 'html' at 0xb77e6fac> >>> 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 0xb77ec26c> + >>> links = list(p.iter("a")) # Returns list of all links >>> links - [<Element a at b7d4f9ec>, <Element a at b7d4fb0c>] + [<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>] >>> for i in links: # Iterates through all found links ... i.attrib["target"] = "blank" >>> tree.write("output.xhtml") @@ -408,12 +510,12 @@ QName Objects .. class:: QName(text_or_uri, tag=None) - QName wrapper. This can be used to wrap a QName attribute value, in order to - get proper namespace handling on output. *text_or_uri* is a string containing - the QName value, in the form {uri}local, or, if the tag argument is given, the - URI part of a QName. If *tag* is given, the first argument is interpreted as an - URI, and this argument is interpreted as a local name. :class:`QName` instances - are opaque. + QName wrapper. This can be used to wrap a QName attribute value, in order + to get proper namespace handling on output. *text_or_uri* is a string + containing the QName value, in the form {uri}local, or, if the tag argument + is given, the URI part of a QName. If *tag* is given, the first argument is + interpreted as an URI, and this argument is interpreted as a local name. + :class:`QName` instances are opaque. .. _elementtree-treebuilder-objects: @@ -424,74 +526,89 @@ TreeBuilder Objects .. class:: TreeBuilder(element_factory=None) - Generic element structure builder. This builder converts a sequence of start, - data, and end method calls to a well-formed element structure. You can use this - class to build an element structure using a custom XML parser, or a parser for - some other XML-like format. The *element_factory* is called to create new - Element instances when given. + Generic element structure builder. This builder converts a sequence of + start, data, and end method calls to a well-formed element structure. You + can use this class to build an element structure using a custom XML parser, + or a parser for some other XML-like format. The *element_factory* is called + to create new :class:`Element` instances when given. .. method:: close() - Flushes the parser buffers, and returns the toplevel document - element. Returns an Element instance. + Flushes the builder buffers, and returns the toplevel document + element. Returns an :class:`Element` instance. .. method:: data(data) - Adds text to the current element. *data* is a string. This should be - either an ASCII-only :class:`bytes` object or a :class:`str` object. + Adds text to the current element. *data* is a string. This should be + either a bytestring, or a Unicode string. .. method:: end(tag) - Closes the current element. *tag* is the element name. Returns the closed - element. + Closes the current element. *tag* is the element name. Returns the + closed element. .. method:: start(tag, attrs) - Opens a new element. *tag* is the element name. *attrs* is a dictionary - containing element attributes. Returns the opened element. + Opens a new element. *tag* is the element name. *attrs* is a dictionary + containing element attributes. Returns the opened element. + + In addition, a custom :class:`TreeBuilder` object can provide the + following method: -.. _elementtree-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:: 3.2 -XMLTreeBuilder Objects ----------------------- +.. _elementtree-xmlparser-objects: -.. class:: XMLTreeBuilder(html=0, target=None) +XMLParser Objects +----------------- - 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. + +.. class:: XMLParser(html=0, target=None, encoding=None) + + :class:`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. *encoding* [1]_ + is optional. If given, the value overrides the encoding specified in the + XML file. .. method:: close() - Finishes feeding data to the parser. Returns an element structure. + Finishes feeding data to the parser. Returns an element structure. .. 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:: 3.2 + Define the :meth:`TreeBuilder.doctype` method on a custom TreeBuilder + target. .. method:: feed(data) - Feeds data to the parser. *data* is encoded 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 +624,7 @@ This is an example of counting the maximum depth of an XML file:: ... return self.maxDepth ... >>> target = MaxDepth() - >>> parser = XMLTreeBuilder(target=target) + >>> parser = XMLParser(target=target) >>> exampleXml = """ ... <a> ... <b> @@ -527,7 +644,6 @@ This is an example of counting the maximum depth of an XML file:: .. rubric:: Footnotes .. [#] The encoding string included in XML output should conform to the - appropriate standards. For example, "UTF-8" is valid, but "UTF8" is - not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl + 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. - |