blob: 892a59aec2f6b919a0331db15856406fa88e2d07 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`xml.etree.ElementTree` --- The ElementTree XML API
2========================================================
3
4.. module:: xml.etree.ElementTree
5 :synopsis: Implementation of the ElementTree API.
6.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
7
8
Florent Xiclunaf15351d2010-03-13 23:24:31 +00009The :class:`Element` type is a flexible container object, designed to store
10hierarchical data structures in memory. The type can be described as a cross
11between a list and a dictionary.
Georg Brandl116aa622007-08-15 14:28:22 +000012
13Each element has a number of properties associated with it:
14
15* a tag which is a string identifying what kind of data this element represents
16 (the element type, in other words).
17
18* a number of attributes, stored in a Python dictionary.
19
20* a text string.
21
22* an optional tail string.
23
24* a number of child elements, stored in a Python sequence
25
Florent Xiclunaf15351d2010-03-13 23:24:31 +000026To create an element instance, use the :class:`Element` constructor or the
27:func:`SubElement` factory function.
Georg Brandl116aa622007-08-15 14:28:22 +000028
29The :class:`ElementTree` class can be used to wrap an element structure, and
30convert it from and to XML.
31
32A C implementation of this API is available as :mod:`xml.etree.cElementTree`.
33
Christian Heimesd8654cf2007-12-02 15:22:16 +000034See http://effbot.org/zone/element-index.htm for tutorials and links to other
Florent Xiclunaf15351d2010-03-13 23:24:31 +000035docs. Fredrik Lundh's page is also the location of the development version of
36the xml.etree.ElementTree.
37
Ezio Melottif8754a62010-03-21 07:16:43 +000038.. versionchanged:: 3.2
Florent Xiclunaf15351d2010-03-13 23:24:31 +000039 The ElementTree API is updated to 1.3. For more information, see
40 `Introducing ElementTree 1.3
41 <http://effbot.org/zone/elementtree-13-intro.htm>`_.
42
Georg Brandl116aa622007-08-15 14:28:22 +000043
44.. _elementtree-functions:
45
46Functions
47---------
48
49
Georg Brandl7f01a132009-09-16 15:58:14 +000050.. function:: Comment(text=None)
Georg Brandl116aa622007-08-15 14:28:22 +000051
Georg Brandlf6945182008-02-01 11:56:49 +000052 Comment element factory. This factory function creates a special element
Florent Xiclunaf15351d2010-03-13 23:24:31 +000053 that will be serialized as an XML comment by the standard serializer. The
54 comment string can be either a bytestring or a Unicode string. *text* is a
55 string containing the comment string. Returns an element instance
Georg Brandlf6945182008-02-01 11:56:49 +000056 representing a comment.
Georg Brandl116aa622007-08-15 14:28:22 +000057
58
59.. function:: dump(elem)
60
Florent Xiclunaf15351d2010-03-13 23:24:31 +000061 Writes an element tree or element structure to sys.stdout. This function
62 should be used for debugging only.
Georg Brandl116aa622007-08-15 14:28:22 +000063
64 The exact output format is implementation dependent. In this version, it's
65 written as an ordinary XML file.
66
67 *elem* is an element tree or an individual element.
68
69
Georg Brandl116aa622007-08-15 14:28:22 +000070.. function:: fromstring(text)
71
Florent Xiclunadddd5e92010-03-14 01:28:07 +000072 Parses an XML section from a string constant. Same as :func:`XML`. *text*
73 is a string containing XML data. Returns an :class:`Element` instance.
Florent Xiclunaf15351d2010-03-13 23:24:31 +000074
75
76.. function:: fromstringlist(sequence, parser=None)
77
78 Parses an XML document from a sequence of string fragments. *sequence* is a
79 list or other sequence containing XML data fragments. *parser* is an
80 optional parser instance. If not given, the standard :class:`XMLParser`
81 parser is used. Returns an :class:`Element` instance.
82
Ezio Melottif8754a62010-03-21 07:16:43 +000083 .. versionadded:: 3.2
Georg Brandl116aa622007-08-15 14:28:22 +000084
85
86.. function:: iselement(element)
87
Florent Xiclunaf15351d2010-03-13 23:24:31 +000088 Checks if an object appears to be a valid element object. *element* is an
89 element instance. Returns a true value if this is an element object.
Georg Brandl116aa622007-08-15 14:28:22 +000090
91
Florent Xiclunaf15351d2010-03-13 23:24:31 +000092.. function:: iterparse(source, events=None, parser=None)
Georg Brandl116aa622007-08-15 14:28:22 +000093
94 Parses an XML section into an element tree incrementally, and reports what's
Florent Xiclunaf15351d2010-03-13 23:24:31 +000095 going on to the user. *source* is a filename or file object containing XML
96 data. *events* is a list of events to report back. If omitted, only "end"
97 events are reported. *parser* is an optional parser instance. If not
98 given, the standard :class:`XMLParser` parser is used. Returns an
99 :term:`iterator` providing ``(event, elem)`` pairs.
Georg Brandl116aa622007-08-15 14:28:22 +0000100
Benjamin Peterson75edad02009-01-01 15:05:06 +0000101 .. note::
102
103 :func:`iterparse` only guarantees that it has seen the ">"
104 character of a starting tag when it emits a "start" event, so the
105 attributes are defined, but the contents of the text and tail attributes
106 are undefined at that point. The same applies to the element children;
107 they may or may not be present.
108
109 If you need a fully populated element, look for "end" events instead.
110
Georg Brandl116aa622007-08-15 14:28:22 +0000111
Georg Brandl7f01a132009-09-16 15:58:14 +0000112.. function:: parse(source, parser=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000113
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000114 Parses an XML section into an element tree. *source* is a filename or file
115 object containing XML data. *parser* is an optional parser instance. If
116 not given, the standard :class:`XMLParser` parser is used. Returns an
117 :class:`ElementTree` instance.
Georg Brandl116aa622007-08-15 14:28:22 +0000118
119
Georg Brandl7f01a132009-09-16 15:58:14 +0000120.. function:: ProcessingInstruction(target, text=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000121
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000122 PI element factory. This factory function creates a special element that
123 will be serialized as an XML processing instruction. *target* is a string
124 containing the PI target. *text* is a string containing the PI contents, if
125 given. Returns an element instance, representing a processing instruction.
126
127
128.. function:: register_namespace(prefix, uri)
129
130 Registers a namespace prefix. The registry is global, and any existing
131 mapping for either the given prefix or the namespace URI will be removed.
132 *prefix* is a namespace prefix. *uri* is a namespace uri. Tags and
133 attributes in this namespace will be serialized with the given prefix, if at
134 all possible.
135
Ezio Melottif8754a62010-03-21 07:16:43 +0000136 .. versionadded:: 3.2
Georg Brandl116aa622007-08-15 14:28:22 +0000137
138
Georg Brandl7f01a132009-09-16 15:58:14 +0000139.. function:: SubElement(parent, tag, attrib={}, **extra)
Georg Brandl116aa622007-08-15 14:28:22 +0000140
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000141 Subelement factory. This function creates an element instance, and appends
142 it to an existing element.
Georg Brandl116aa622007-08-15 14:28:22 +0000143
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000144 The element name, attribute names, and attribute values can be either
145 bytestrings or Unicode strings. *parent* is the parent element. *tag* is
146 the subelement name. *attrib* is an optional dictionary, containing element
147 attributes. *extra* contains additional attributes, given as keyword
148 arguments. Returns an element instance.
Georg Brandl116aa622007-08-15 14:28:22 +0000149
150
Florent Xiclunadddd5e92010-03-14 01:28:07 +0000151.. function:: tostring(element, encoding=None, method="xml")
Georg Brandl116aa622007-08-15 14:28:22 +0000152
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000153 Generates a string representation of an XML element, including all
Florent Xiclunadddd5e92010-03-14 01:28:07 +0000154 subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is
155 the output encoding (default is None). *method* is either ``"xml"``,
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000156 ``"html"`` or ``"text"`` (default is ``"xml"``). Returns an (optionally)
157 encoded string containing the XML data.
Georg Brandl116aa622007-08-15 14:28:22 +0000158
159
Florent Xiclunadddd5e92010-03-14 01:28:07 +0000160.. function:: tostringlist(element, encoding=None, method="xml")
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000161
162 Generates a string representation of an XML element, including all
Florent Xiclunadddd5e92010-03-14 01:28:07 +0000163 subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is
164 the output encoding (default is None). *method* is either ``"xml"``,
165 ``"html"`` or ``"text"`` (default is ``"xml"``). Returns a list of
166 (optionally) encoded strings containing the XML data. It does not guarantee
167 any specific sequence, except that ``"".join(tostringlist(element)) ==
168 tostring(element)``.
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000169
Ezio Melottif8754a62010-03-21 07:16:43 +0000170 .. versionadded:: 3.2
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000171
172
173.. function:: XML(text, parser=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000174
175 Parses an XML section from a string constant. This function can be used to
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000176 embed "XML literals" in Python code. *text* is a string containing XML
177 data. *parser* is an optional parser instance. If not given, the standard
178 :class:`XMLParser` parser is used. Returns an :class:`Element` instance.
Georg Brandl116aa622007-08-15 14:28:22 +0000179
180
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000181.. function:: XMLID(text, parser=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000182
183 Parses an XML section from a string constant, and also returns a dictionary
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000184 which maps from element id:s to elements. *text* is a string containing XML
185 data. *parser* is an optional parser instance. If not given, the standard
186 :class:`XMLParser` parser is used. Returns a tuple containing an
187 :class:`Element` instance and a dictionary.
Georg Brandl116aa622007-08-15 14:28:22 +0000188
189
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000190.. _elementtree-element-objects:
Georg Brandl116aa622007-08-15 14:28:22 +0000191
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000192Element Objects
193---------------
Georg Brandl116aa622007-08-15 14:28:22 +0000194
Georg Brandl116aa622007-08-15 14:28:22 +0000195
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000196.. class:: Element(tag, attrib={}, **extra)
Georg Brandl116aa622007-08-15 14:28:22 +0000197
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000198 Element class. This class defines the Element interface, and provides a
199 reference implementation of this interface.
Georg Brandl116aa622007-08-15 14:28:22 +0000200
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000201 The element name, attribute names, and attribute values can be either
202 bytestrings or Unicode strings. *tag* is the element name. *attrib* is
203 an optional dictionary, containing element attributes. *extra* contains
204 additional attributes, given as keyword arguments.
Georg Brandl116aa622007-08-15 14:28:22 +0000205
206
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000207 .. attribute:: tag
Georg Brandl116aa622007-08-15 14:28:22 +0000208
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000209 A string identifying what kind of data this element represents (the
210 element type, in other words).
Georg Brandl116aa622007-08-15 14:28:22 +0000211
212
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000213 .. attribute:: text
Georg Brandl116aa622007-08-15 14:28:22 +0000214
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000215 The *text* attribute can be used to hold additional data associated with
216 the element. As the name implies this attribute is usually a string but
217 may be any application-specific object. If the element is created from
218 an XML file the attribute will contain any text found between the element
219 tags.
Georg Brandl116aa622007-08-15 14:28:22 +0000220
221
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000222 .. attribute:: tail
Georg Brandl116aa622007-08-15 14:28:22 +0000223
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000224 The *tail* attribute can be used to hold additional data associated with
225 the element. This attribute is usually a string but may be any
226 application-specific object. If the element is created from an XML file
227 the attribute will contain any text found after the element's end tag and
228 before the next tag.
Georg Brandl116aa622007-08-15 14:28:22 +0000229
Georg Brandl116aa622007-08-15 14:28:22 +0000230
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000231 .. attribute:: attrib
Georg Brandl116aa622007-08-15 14:28:22 +0000232
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000233 A dictionary containing the element's attributes. Note that while the
234 *attrib* value is always a real mutable Python dictionary, an ElementTree
235 implementation may choose to use another internal representation, and
236 create the dictionary only if someone asks for it. To take advantage of
237 such implementations, use the dictionary methods below whenever possible.
Georg Brandl116aa622007-08-15 14:28:22 +0000238
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000239 The following dictionary-like methods work on the element attributes.
Georg Brandl116aa622007-08-15 14:28:22 +0000240
241
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000242 .. method:: clear()
Georg Brandl116aa622007-08-15 14:28:22 +0000243
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000244 Resets an element. This function removes all subelements, clears all
245 attributes, and sets the text and tail attributes to None.
Georg Brandl116aa622007-08-15 14:28:22 +0000246
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000247
248 .. method:: get(key, default=None)
249
250 Gets the element attribute named *key*.
251
252 Returns the attribute value, or *default* if the attribute was not found.
253
254
255 .. method:: items()
256
257 Returns the element attributes as a sequence of (name, value) pairs. The
258 attributes are returned in an arbitrary order.
259
260
261 .. method:: keys()
262
263 Returns the elements attribute names as a list. The names are returned
264 in an arbitrary order.
265
266
267 .. method:: set(key, value)
268
269 Set the attribute *key* on the element to *value*.
270
271 The following methods work on the element's children (subelements).
272
273
274 .. method:: append(subelement)
275
276 Adds the element *subelement* to the end of this elements internal list
277 of subelements.
278
279
280 .. method:: extend(subelements)
Georg Brandl116aa622007-08-15 14:28:22 +0000281
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000282 Appends *subelements* from a sequence object with zero or more elements.
283 Raises :exc:`AssertionError` if a subelement is not a valid object.
Georg Brandl116aa622007-08-15 14:28:22 +0000284
Ezio Melottif8754a62010-03-21 07:16:43 +0000285 .. versionadded:: 3.2
Georg Brandl116aa622007-08-15 14:28:22 +0000286
Georg Brandl116aa622007-08-15 14:28:22 +0000287
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000288 .. method:: find(match)
Georg Brandl116aa622007-08-15 14:28:22 +0000289
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000290 Finds the first subelement matching *match*. *match* may be a tag name
291 or path. Returns an element instance or ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000292
Georg Brandl116aa622007-08-15 14:28:22 +0000293
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000294 .. method:: findall(match)
Georg Brandl116aa622007-08-15 14:28:22 +0000295
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000296 Finds all matching subelements, by tag name or path. Returns a list
297 containing all matching elements in document order.
Georg Brandl116aa622007-08-15 14:28:22 +0000298
Georg Brandl116aa622007-08-15 14:28:22 +0000299
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000300 .. method:: findtext(match, default=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000301
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000302 Finds text for the first subelement matching *match*. *match* may be
303 a tag name or path. Returns the text content of the first matching
304 element, or *default* if no element was found. Note that if the matching
305 element has no text content an empty string is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000306
Georg Brandl116aa622007-08-15 14:28:22 +0000307
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000308 .. method:: getchildren()
Georg Brandl116aa622007-08-15 14:28:22 +0000309
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000310 .. deprecated:: 2.7
311 Use ``list(elem)`` or iteration.
Georg Brandl116aa622007-08-15 14:28:22 +0000312
Georg Brandl116aa622007-08-15 14:28:22 +0000313
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000314 .. method:: getiterator(tag=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000315
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000316 .. deprecated:: 2.7
317 Use method :meth:`Element.iter` instead.
Georg Brandl116aa622007-08-15 14:28:22 +0000318
Georg Brandl116aa622007-08-15 14:28:22 +0000319
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000320 .. method:: insert(index, element)
Georg Brandl116aa622007-08-15 14:28:22 +0000321
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000322 Inserts a subelement at the given position in this element.
Georg Brandl116aa622007-08-15 14:28:22 +0000323
Georg Brandl116aa622007-08-15 14:28:22 +0000324
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000325 .. method:: iter(tag=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000326
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000327 Creates a tree :term:`iterator` with the current element as the root.
328 The iterator iterates over this element and all elements below it, in
329 document (depth first) order. If *tag* is not ``None`` or ``'*'``, only
330 elements whose tag equals *tag* are returned from the iterator. If the
331 tree structure is modified during iteration, the result is undefined.
Georg Brandl116aa622007-08-15 14:28:22 +0000332
Georg Brandl116aa622007-08-15 14:28:22 +0000333
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000334 .. method:: iterfind(match)
Georg Brandl116aa622007-08-15 14:28:22 +0000335
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000336 Finds all matching subelements, by tag name or path. Returns an iterable
337 yielding all matching elements in document order.
Georg Brandl116aa622007-08-15 14:28:22 +0000338
Ezio Melottif8754a62010-03-21 07:16:43 +0000339 .. versionadded:: 3.2
Georg Brandl116aa622007-08-15 14:28:22 +0000340
Georg Brandl116aa622007-08-15 14:28:22 +0000341
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000342 .. method:: itertext()
Georg Brandl116aa622007-08-15 14:28:22 +0000343
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000344 Creates a text iterator. The iterator loops over this element and all
345 subelements, in document order, and returns all inner text.
Georg Brandl116aa622007-08-15 14:28:22 +0000346
Ezio Melottif8754a62010-03-21 07:16:43 +0000347 .. versionadded:: 3.2
Georg Brandl116aa622007-08-15 14:28:22 +0000348
349
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000350 .. method:: makeelement(tag, attrib)
Georg Brandl116aa622007-08-15 14:28:22 +0000351
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000352 Creates a new element object of the same type as this element. Do not
353 call this method, use the :func:`SubElement` factory function instead.
Georg Brandl116aa622007-08-15 14:28:22 +0000354
355
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000356 .. method:: remove(subelement)
Georg Brandl116aa622007-08-15 14:28:22 +0000357
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000358 Removes *subelement* from the element. Unlike the find\* methods this
359 method compares elements based on the instance identity, not on tag value
360 or contents.
Georg Brandl116aa622007-08-15 14:28:22 +0000361
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000362 :class:`Element` objects also support the following sequence type methods
363 for working with subelements: :meth:`__delitem__`, :meth:`__getitem__`,
364 :meth:`__setitem__`, :meth:`__len__`.
Georg Brandl116aa622007-08-15 14:28:22 +0000365
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000366 Caution: Elements with no subelements will test as ``False``. This behavior
367 will change in future versions. Use specific ``len(elem)`` or ``elem is
368 None`` test instead. ::
Georg Brandl116aa622007-08-15 14:28:22 +0000369
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000370 element = root.find('foo')
Georg Brandl116aa622007-08-15 14:28:22 +0000371
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000372 if not element: # careful!
373 print("element not found, or element has no subelements")
Georg Brandl116aa622007-08-15 14:28:22 +0000374
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000375 if element is None:
376 print("element not found")
Georg Brandl116aa622007-08-15 14:28:22 +0000377
378
379.. _elementtree-elementtree-objects:
380
381ElementTree Objects
382-------------------
383
384
Georg Brandl7f01a132009-09-16 15:58:14 +0000385.. class:: ElementTree(element=None, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000386
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000387 ElementTree wrapper class. This class represents an entire element
388 hierarchy, and adds some extra support for serialization to and from
389 standard XML.
Georg Brandl116aa622007-08-15 14:28:22 +0000390
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000391 *element* is the root element. The tree is initialized with the contents
392 of the XML *file* if given.
Georg Brandl116aa622007-08-15 14:28:22 +0000393
394
Benjamin Petersone41251e2008-04-25 01:59:09 +0000395 .. method:: _setroot(element)
Georg Brandl116aa622007-08-15 14:28:22 +0000396
Benjamin Petersone41251e2008-04-25 01:59:09 +0000397 Replaces the root element for this tree. This discards the current
398 contents of the tree, and replaces it with the given element. Use with
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000399 care. *element* is an element instance.
Georg Brandl116aa622007-08-15 14:28:22 +0000400
401
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000402 .. method:: find(match)
Georg Brandl116aa622007-08-15 14:28:22 +0000403
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000404 Finds the first toplevel element matching *match*. *match* may be a tag
405 name or path. Same as getroot().find(match). Returns the first matching
406 element, or ``None`` if no element was found.
Georg Brandl116aa622007-08-15 14:28:22 +0000407
408
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000409 .. method:: findall(match)
Georg Brandl116aa622007-08-15 14:28:22 +0000410
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000411 Finds all matching subelements, by tag name or path. Same as
412 getroot().findall(match). *match* may be a tag name or path. Returns a
413 list containing all matching elements, in document order.
Georg Brandl116aa622007-08-15 14:28:22 +0000414
415
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000416 .. method:: findtext(match, default=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000417
Benjamin Petersone41251e2008-04-25 01:59:09 +0000418 Finds the element text for the first toplevel element with given tag.
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000419 Same as getroot().findtext(match). *match* may be a tag name or path.
420 *default* is the value to return if the element was not found. Returns
421 the text content of the first matching element, or the default value no
422 element was found. Note that if the element is found, but has no text
423 content, this method returns an empty string.
Georg Brandl116aa622007-08-15 14:28:22 +0000424
425
Georg Brandl7f01a132009-09-16 15:58:14 +0000426 .. method:: getiterator(tag=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000427
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000428 .. deprecated:: 2.7
429 Use method :meth:`ElementTree.iter` instead.
Georg Brandl116aa622007-08-15 14:28:22 +0000430
431
Benjamin Petersone41251e2008-04-25 01:59:09 +0000432 .. method:: getroot()
Benjamin Petersone41251e2008-04-25 01:59:09 +0000433 Returns the root element for this tree.
Georg Brandl116aa622007-08-15 14:28:22 +0000434
435
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000436 .. method:: iter(tag=None)
437
438 Creates and returns a tree iterator for the root element. The iterator
439 loops over all elements in this tree, in section order. *tag* is the tag
440 to look for (default is to return all elements)
441
442
443 .. method:: iterfind(match)
444
445 Finds all matching subelements, by tag name or path. Same as
446 getroot().iterfind(match). Returns an iterable yielding all matching
447 elements in document order.
448
Ezio Melottif8754a62010-03-21 07:16:43 +0000449 .. versionadded:: 3.2
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000450
451
Georg Brandl7f01a132009-09-16 15:58:14 +0000452 .. method:: parse(source, parser=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000453
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000454 Loads an external XML section into this element tree. *source* is a file
455 name or file object. *parser* is an optional parser instance. If not
456 given, the standard XMLParser parser is used. Returns the section
Benjamin Petersone41251e2008-04-25 01:59:09 +0000457 root element.
Georg Brandl116aa622007-08-15 14:28:22 +0000458
459
Florent Xiclunadddd5e92010-03-14 01:28:07 +0000460 .. method:: write(file, encoding=None, xml_declaration=None, method="xml")
Georg Brandl116aa622007-08-15 14:28:22 +0000461
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000462 Writes the element tree to a file, as XML. *file* is a file name, or a
463 file object opened for writing. *encoding* [1]_ is the output encoding
464 (default is None). *xml_declaration* controls if an XML declaration
465 should be added to the file. Use False for never, True for always, None
466 for only if not US-ASCII or UTF-8 (default is None). *method* is either
467 ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). Returns an
468 (optionally) encoded string.
Georg Brandl116aa622007-08-15 14:28:22 +0000469
Christian Heimesd8654cf2007-12-02 15:22:16 +0000470This is the XML file that is going to be manipulated::
471
472 <html>
473 <head>
474 <title>Example page</title>
475 </head>
476 <body>
Georg Brandl48310cd2009-01-03 21:18:54 +0000477 <p>Moved to <a href="http://example.org/">example.org</a>
Christian Heimesd8654cf2007-12-02 15:22:16 +0000478 or <a href="http://example.com/">example.com</a>.</p>
479 </body>
480 </html>
481
482Example of changing the attribute "target" of every link in first paragraph::
483
484 >>> from xml.etree.ElementTree import ElementTree
485 >>> tree = ElementTree()
486 >>> tree.parse("index.xhtml")
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000487 <Element 'html' at 0xb77e6fac>
Christian Heimesd8654cf2007-12-02 15:22:16 +0000488 >>> p = tree.find("body/p") # Finds first occurrence of tag p in body
489 >>> p
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000490 <Element 'p' at 0xb77ec26c>
491 >>> links = list(p.iter("a")) # Returns list of all links
Christian Heimesd8654cf2007-12-02 15:22:16 +0000492 >>> links
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000493 [<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
Christian Heimesd8654cf2007-12-02 15:22:16 +0000494 >>> for i in links: # Iterates through all found links
495 ... i.attrib["target"] = "blank"
496 >>> tree.write("output.xhtml")
Georg Brandl116aa622007-08-15 14:28:22 +0000497
498.. _elementtree-qname-objects:
499
500QName Objects
501-------------
502
503
Georg Brandl7f01a132009-09-16 15:58:14 +0000504.. class:: QName(text_or_uri, tag=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000505
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000506 QName wrapper. This can be used to wrap a QName attribute value, in order
507 to get proper namespace handling on output. *text_or_uri* is a string
508 containing the QName value, in the form {uri}local, or, if the tag argument
509 is given, the URI part of a QName. If *tag* is given, the first argument is
510 interpreted as an URI, and this argument is interpreted as a local name.
511 :class:`QName` instances are opaque.
Georg Brandl116aa622007-08-15 14:28:22 +0000512
513
514.. _elementtree-treebuilder-objects:
515
516TreeBuilder Objects
517-------------------
518
519
Georg Brandl7f01a132009-09-16 15:58:14 +0000520.. class:: TreeBuilder(element_factory=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000521
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000522 Generic element structure builder. This builder converts a sequence of
523 start, data, and end method calls to a well-formed element structure. You
524 can use this class to build an element structure using a custom XML parser,
525 or a parser for some other XML-like format. The *element_factory* is called
526 to create new :class:`Element` instances when given.
Georg Brandl116aa622007-08-15 14:28:22 +0000527
528
Benjamin Petersone41251e2008-04-25 01:59:09 +0000529 .. method:: close()
Georg Brandl116aa622007-08-15 14:28:22 +0000530
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000531 Flushes the builder buffers, and returns the toplevel document
532 element. Returns an :class:`Element` instance.
Georg Brandl116aa622007-08-15 14:28:22 +0000533
534
Benjamin Petersone41251e2008-04-25 01:59:09 +0000535 .. method:: data(data)
Georg Brandl116aa622007-08-15 14:28:22 +0000536
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000537 Adds text to the current element. *data* is a string. This should be
538 either a bytestring, or a Unicode string.
Georg Brandl116aa622007-08-15 14:28:22 +0000539
540
Benjamin Petersone41251e2008-04-25 01:59:09 +0000541 .. method:: end(tag)
Georg Brandl116aa622007-08-15 14:28:22 +0000542
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000543 Closes the current element. *tag* is the element name. Returns the
544 closed element.
Georg Brandl116aa622007-08-15 14:28:22 +0000545
546
Benjamin Petersone41251e2008-04-25 01:59:09 +0000547 .. method:: start(tag, attrs)
Georg Brandl116aa622007-08-15 14:28:22 +0000548
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000549 Opens a new element. *tag* is the element name. *attrs* is a dictionary
550 containing element attributes. Returns the opened element.
Georg Brandl116aa622007-08-15 14:28:22 +0000551
552
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000553 In addition, a custom :class:`TreeBuilder` object can provide the
554 following method:
Georg Brandl116aa622007-08-15 14:28:22 +0000555
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000556 .. method:: doctype(name, pubid, system)
557
558 Handles a doctype declaration. *name* is the doctype name. *pubid* is
559 the public identifier. *system* is the system identifier. This method
560 does not exist on the default :class:`TreeBuilder` class.
561
Ezio Melottif8754a62010-03-21 07:16:43 +0000562 .. versionadded:: 3.2
Georg Brandl116aa622007-08-15 14:28:22 +0000563
564
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000565.. _elementtree-xmlparser-objects:
Georg Brandl116aa622007-08-15 14:28:22 +0000566
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000567XMLParser Objects
568-----------------
569
570
571.. class:: XMLParser(html=0, target=None, encoding=None)
572
573 :class:`Element` structure builder for XML source data, based on the expat
574 parser. *html* are predefined HTML entities. This flag is not supported by
575 the current implementation. *target* is the target object. If omitted, the
576 builder uses an instance of the standard TreeBuilder class. *encoding* [1]_
577 is optional. If given, the value overrides the encoding specified in the
578 XML file.
Georg Brandl116aa622007-08-15 14:28:22 +0000579
580
Benjamin Petersone41251e2008-04-25 01:59:09 +0000581 .. method:: close()
Georg Brandl116aa622007-08-15 14:28:22 +0000582
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000583 Finishes feeding data to the parser. Returns an element structure.
Georg Brandl116aa622007-08-15 14:28:22 +0000584
585
Benjamin Petersone41251e2008-04-25 01:59:09 +0000586 .. method:: doctype(name, pubid, system)
Georg Brandl116aa622007-08-15 14:28:22 +0000587
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000588 .. deprecated:: 2.7
589 Define the :meth:`TreeBuilder.doctype` method on a custom TreeBuilder
590 target.
Georg Brandl116aa622007-08-15 14:28:22 +0000591
592
Benjamin Petersone41251e2008-04-25 01:59:09 +0000593 .. method:: feed(data)
Georg Brandl116aa622007-08-15 14:28:22 +0000594
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000595 Feeds data to the parser. *data* is encoded data.
Georg Brandl116aa622007-08-15 14:28:22 +0000596
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000597:meth:`XMLParser.feed` calls *target*\'s :meth:`start` method
Christian Heimesd8654cf2007-12-02 15:22:16 +0000598for each opening tag, its :meth:`end` method for each closing tag,
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000599and data is processed by method :meth:`data`. :meth:`XMLParser.close`
Georg Brandl48310cd2009-01-03 21:18:54 +0000600calls *target*\'s method :meth:`close`.
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000601:class:`XMLParser` can be used not only for building a tree structure.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000602This is an example of counting the maximum depth of an XML file::
603
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000604 >>> from xml.etree.ElementTree import XMLParser
Christian Heimesd8654cf2007-12-02 15:22:16 +0000605 >>> class MaxDepth: # The target object of the parser
606 ... maxDepth = 0
607 ... depth = 0
608 ... def start(self, tag, attrib): # Called for each opening tag.
Georg Brandl48310cd2009-01-03 21:18:54 +0000609 ... self.depth += 1
Christian Heimesd8654cf2007-12-02 15:22:16 +0000610 ... if self.depth > self.maxDepth:
611 ... self.maxDepth = self.depth
612 ... def end(self, tag): # Called for each closing tag.
613 ... self.depth -= 1
Georg Brandl48310cd2009-01-03 21:18:54 +0000614 ... def data(self, data):
Christian Heimesd8654cf2007-12-02 15:22:16 +0000615 ... pass # We do not need to do anything with data.
616 ... def close(self): # Called when all data has been parsed.
617 ... return self.maxDepth
Georg Brandl48310cd2009-01-03 21:18:54 +0000618 ...
Christian Heimesd8654cf2007-12-02 15:22:16 +0000619 >>> target = MaxDepth()
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000620 >>> parser = XMLParser(target=target)
Christian Heimesd8654cf2007-12-02 15:22:16 +0000621 >>> exampleXml = """
622 ... <a>
623 ... <b>
624 ... </b>
625 ... <b>
626 ... <c>
627 ... <d>
628 ... </d>
629 ... </c>
630 ... </b>
631 ... </a>"""
632 >>> parser.feed(exampleXml)
633 >>> parser.close()
634 4
Christian Heimesb186d002008-03-18 15:15:01 +0000635
636
637.. rubric:: Footnotes
638
639.. [#] The encoding string included in XML output should conform to the
Florent Xiclunaf15351d2010-03-13 23:24:31 +0000640 appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
641 not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
Benjamin Petersonad3d5c22009-02-26 03:38:59 +0000642 and http://www.iana.org/assignments/character-sets.