source: exist/trunk/python/elementtree-1.3a6-20070310-badc/docs/pythondoc-elementtree.ElementTree.html @ 3578

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/exist/trunk/python/elementtree-1.3a6-20070310-badc/docs/pythondoc-elementtree.ElementTree.html@3578
Revision 3578, 39.3 KB checked in by pjkersha, 11 years ago (diff)

Latest releases from Fredrik Lundh. 10 March release has exclusive C14N support with namespace prefixes.

Line 
1<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
2<html>
3<head>
4<meta http-equiv='Content-Type' content='text/html; charset=us-ascii' />
5<title>The elementtree.ElementTree Module</title>
6<link rel='stylesheet' href='effbot.css' type='text/css' />
7</head>
8<body>
9<h1>The elementtree.ElementTree Module</h1>
10<p>The <b>Element</b> type is a flexible container object, designed to
11store hierarchical data structures in memory. The type can be
12described as a cross between a list and a dictionary.
13</p><p>
14Each element has a number of properties associated with it:
15<ul>
16<li>a <i>tag</i>. This is a string identifying what kind of data
17this element represents (the element type, in other words).</li>
18<li>a number of <i>attributes</i>, stored in a Python dictionary.</li>
19<li>a <i>text</i> string.</li>
20<li>an optional <i>tail</i> string.</li>
21<li>a number of <i>child elements</i>, stored in a Python sequence</li>
22</ul>
23
24To create an element instance, use the <a class="link" href="#elementtree.ElementTree.Element-class"><b>Element</b></a> constructor
25or the <a class="link" href="#elementtree.ElementTree.SubElement-function"><b>SubElement</b></a> factory function.
26</p><p>
27The <a class="link" href="#elementtree.ElementTree.ElementTree-class"><b>ElementTree</b></a> class can be used to wrap an element
28structure, and convert it from and to XML.
29</p><h2>Module Contents</h2>
30<dl>
31<dt><a id='elementtree.ElementTree.Comment-function' name='elementtree.ElementTree.Comment-function'><b>Comment(text=None)</b></a> &rArr; Element [<a href='#elementtree.ElementTree.Comment-function'>#</a>]</dt>
32<dd>
33<p>Comment element factory.  This factory function creates a special
34element that will be serialized as an XML comment by the standard
35serializer.
36</p><p>
37The comment string can be either an 8-bit ASCII string or a Unicode
38string.
39
40</p><dl>
41<dt><i>text</i></dt>
42<dd>
43A string containing the comment string.</dd>
44<dt>Returns:</dt>
45<dd>
46An element instance, representing a comment.</dd>
47</dl><br />
48</dd>
49<dt><a id='elementtree.ElementTree.dump-function' name='elementtree.ElementTree.dump-function'><b>dump(elem)</b></a> [<a href='#elementtree.ElementTree.dump-function'>#</a>]</dt>
50<dd>
51<p>Writes an element tree or element structure to sys.stdout.  This
52function should be used for debugging only.
53</p><p>
54The exact output format is implementation dependent.  In this
55version, it's written as an ordinary XML file.
56
57</p><dl>
58<dt><i>elem</i></dt>
59<dd>
60An element tree or an individual element.</dd>
61</dl><br />
62</dd>
63<dt><b>Element(tag, attrib={}, **extra)</b> (class) [<a href='#elementtree.ElementTree.Element-class'>#</a>]</dt>
64<dd>
65<p>Element class.</p>
66<dl>
67<dt><i>tag</i></dt>
68<dd>
69The element name.</dd>
70<dt><i>attrib</i></dt>
71<dd>
72An optional dictionary, containing element attributes.</dd>
73<dt><i>**extra</i></dt>
74<dd>
75Additional attributes, given as keyword arguments.</dd>
76</dl><br />
77<p>For more information about this class, see <a href='#elementtree.ElementTree.Element-class'><i>The Element Class</i></a>.</p>
78</dd>
79<dt><b>ElementTree(element=None, file=None)</b> (class) [<a href='#elementtree.ElementTree.ElementTree-class'>#</a>]</dt>
80<dd>
81<p>ElementTree wrapper class.</p>
82<dl>
83<dt><i>element</i></dt>
84<dd>
85Optional root element.</dd>
86<dt><i>file=</i></dt>
87<dd>
88Optional file handle or file name.  If given, the
89    tree is initialized with the contents of this XML file.</dd>
90</dl><br />
91<p>For more information about this class, see <a href='#elementtree.ElementTree.ElementTree-class'><i>The ElementTree Class</i></a>.</p>
92</dd>
93<dt><a id='elementtree.ElementTree.fromstring-variable' name='elementtree.ElementTree.fromstring-variable'><b>fromstring</b></a> (variable) [<a href='#elementtree.ElementTree.fromstring-variable'>#</a>]</dt>
94<dd>
95<p>Parses an XML document from a string constant.  Same as <a class="link" href="#elementtree.ElementTree.XML-function"><b>XML</b></a>.
96
97</p><dl>
98<dt><i>source</i></dt>
99<dd>
100A string containing XML data.</dd>
101<dt>Returns:</dt>
102<dd>
103An Element instance.</dd>
104</dl><br />
105</dd>
106<dt><a id='elementtree.ElementTree.fromstringlist-function' name='elementtree.ElementTree.fromstringlist-function'><b>fromstringlist(sequence, parser=None)</b></a> &rArr; Element [<a href='#elementtree.ElementTree.fromstringlist-function'>#</a>]</dt>
107<dd>
108<p>Parses an XML document from a sequence of string fragments.</p>
109<dl>
110<dt><i>sequence</i></dt>
111<dd>
112A list or other sequence containing XML data fragments.</dd>
113<dt><i>parser</i></dt>
114<dd>
115An optional parser instance.  If not given, the
116    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
117</dd>
118<dt>Returns:</dt>
119<dd>
120An Element instance.</dd>
121</dl><br />
122</dd>
123<dt><a id='elementtree.ElementTree.iselement-function' name='elementtree.ElementTree.iselement-function'><b>iselement(element)</b></a> &rArr; flag [<a href='#elementtree.ElementTree.iselement-function'>#</a>]</dt>
124<dd>
125<p>Checks if an object appears to be a valid element object.</p>
126<dl>
127<dt><i>An</i></dt>
128<dd>
129element instance.</dd>
130<dt>Returns:</dt>
131<dd>
132A true value if this is an element object.</dd>
133</dl><br />
134</dd>
135<dt><a id='elementtree.ElementTree.iterparse-function' name='elementtree.ElementTree.iterparse-function'><b>iterparse(source, events=None, parser=None)</b></a> [<a href='#elementtree.ElementTree.iterparse-function'>#</a>]</dt>
136<dd>
137<p>Parses an XML document into an element tree incrementally, and reports
138what's going on to the user.</p>
139<dl>
140<dt><i>source</i></dt>
141<dd>
142A filename or file object containing XML data.</dd>
143<dt><i>events</i></dt>
144<dd>
145A list of events to report back.  If omitted, only &quot;end&quot;
146    events are reported.</dd>
147<dt><i>parser</i></dt>
148<dd>
149An optional parser instance.  If not given, the
150    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
151</dd>
152<dt>Returns:</dt>
153<dd>
154A (event, elem) iterator.</dd>
155</dl><br />
156</dd>
157<dt><a id='elementtree.ElementTree.parse-function' name='elementtree.ElementTree.parse-function'><b>parse(source, parser=None)</b></a> [<a href='#elementtree.ElementTree.parse-function'>#</a>]</dt>
158<dd>
159<p>Parses an XML document into an element tree.</p>
160<dl>
161<dt><i>source</i></dt>
162<dd>
163A filename or file object containing XML data.</dd>
164<dt><i>parser</i></dt>
165<dd>
166An optional parser instance.  If not given, the
167    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
168</dd>
169<dt>Returns:</dt>
170<dd>
171An ElementTree instance</dd>
172</dl><br />
173</dd>
174<dt><b>ParseError</b> (class)  [<a href='#elementtree.ElementTree.ParseError-class'>#</a>]</dt>
175<dd>
176<p>Parser error.</p>
177<p>For more information about this class, see <a href='#elementtree.ElementTree.ParseError-class'><i>The ParseError Class</i></a>.</p>
178</dd>
179<dt><a id='elementtree.ElementTree.ProcessingInstruction-function' name='elementtree.ElementTree.ProcessingInstruction-function'><b>ProcessingInstruction(target, text=None)</b></a> &rArr; Element [<a href='#elementtree.ElementTree.ProcessingInstruction-function'>#</a>]</dt>
180<dd>
181<p>PI element factory.  This factory function creates a special element
182that will be serialized as an XML processing instruction by the standard
183serializer.</p>
184<dl>
185<dt><i>target</i></dt>
186<dd>
187A string containing the PI target.</dd>
188<dt><i>text</i></dt>
189<dd>
190A string containing the PI contents, if any.</dd>
191<dt>Returns:</dt>
192<dd>
193An element instance, representing a PI.</dd>
194</dl><br />
195</dd>
196<dt><b>QName(text_or_uri, tag=None)</b> (class) [<a href='#elementtree.ElementTree.QName-class'>#</a>]</dt>
197<dd>
198<p>QName wrapper.</p>
199<dl>
200<dt><i>text</i></dt>
201<dd>
202A string containing the QName value, in the form {uri}local,
203    or, if the tag argument is given, the URI part of a QName.</dd>
204<dt><i>tag</i></dt>
205<dd>
206Optional tag.  If given, the first argument is interpreted as
207    an URI, and this argument is interpreted as a local name.</dd>
208<dt>Returns:</dt>
209<dd>
210An opaque object, representing the QName.</dd>
211</dl><br />
212<p>For more information about this class, see <a href='#elementtree.ElementTree.QName-class'><i>The QName Class</i></a>.</p>
213</dd>
214<dt><a id='elementtree.ElementTree.register_namespace-function' name='elementtree.ElementTree.register_namespace-function'><b>register_namespace(prefix, uri)</b></a> [<a href='#elementtree.ElementTree.register_namespace-function'>#</a>]</dt>
215<dd>
216<p>Registers a namespace prefix.  The registry is global, and any
217existing mapping for either the given prefix or the namespace URI
218will be removed.</p>
219<dl>
220<dt><i>prefix</i></dt>
221<dd>
222Namespace prefix.</dd>
223<dt><i>uri</i></dt>
224<dd>
225Namespace uri.  Tags and attributes in this namespace
226    will be serialized with the given prefix, if at all possible.</dd>
227<dt>Raises <b>ValueError</b>:</dt><dd>
228If the prefix is reserved, or is otherwise
229    invalid.</dd>
230</dl><br />
231</dd>
232<dt><a id='elementtree.ElementTree.SubElement-function' name='elementtree.ElementTree.SubElement-function'><b>SubElement(parent, tag, attrib={}, **extra)</b></a> &rArr; Element [<a href='#elementtree.ElementTree.SubElement-function'>#</a>]</dt>
233<dd>
234<p>Subelement factory.  This function creates an element instance, and
235appends it to an existing element.
236</p><p>
237The element name, attribute names, and attribute values can be
238either 8-bit ASCII strings or Unicode strings.
239
240</p><dl>
241<dt><i>parent</i></dt>
242<dd>
243The parent element.</dd>
244<dt><i>tag</i></dt>
245<dd>
246The subelement name.</dd>
247<dt><i>attrib</i></dt>
248<dd>
249An optional dictionary, containing element attributes.</dd>
250<dt><i>**extra</i></dt>
251<dd>
252Additional attributes, given as keyword arguments.</dd>
253<dt>Returns:</dt>
254<dd>
255An element instance.</dd>
256</dl><br />
257</dd>
258<dt><a id='elementtree.ElementTree.tostring-function' name='elementtree.ElementTree.tostring-function'><b>tostring(element, encoding=None, method=None)</b></a> &rArr; string [<a href='#elementtree.ElementTree.tostring-function'>#</a>]</dt>
259<dd>
260<p>Generates a string representation of an XML element, including all
261subelements.</p>
262<dl>
263<dt><i>element</i></dt>
264<dd>
265An Element instance.</dd>
266<dt>Returns:</dt>
267<dd>
268An encoded string containing the XML data.</dd>
269</dl><br />
270</dd>
271<dt><a id='elementtree.ElementTree.tostringlist-function' name='elementtree.ElementTree.tostringlist-function'><b>tostringlist(element, encoding=None)</b></a> &rArr; sequence [<a href='#elementtree.ElementTree.tostringlist-function'>#</a>]</dt>
272<dd>
273<p>Generates a string representation of an XML element, including all
274subelements.  The string is returned as a sequence of string fragments.</p>
275<dl>
276<dt><i>element</i></dt>
277<dd>
278An Element instance.</dd>
279<dt>Returns:</dt>
280<dd>
281A sequence object containing the XML data.</dd>
282</dl><br />
283</dd>
284<dt><b>TreeBuilder(element_factory=None)</b> (class) [<a href='#elementtree.ElementTree.TreeBuilder-class'>#</a>]</dt>
285<dd>
286<p>Generic element structure builder.</p>
287<dl>
288<dt><i>element_factory</i></dt>
289<dd>
290Optional element factory.  This factory
291   is called to create new Element instances, as necessary.</dd>
292</dl><br />
293<p>For more information about this class, see <a href='#elementtree.ElementTree.TreeBuilder-class'><i>The TreeBuilder Class</i></a>.</p>
294</dd>
295<dt><a id='elementtree.ElementTree.XML-function' name='elementtree.ElementTree.XML-function'><b>XML(text, parser=None)</b></a> &rArr; Element [<a href='#elementtree.ElementTree.XML-function'>#</a>]</dt>
296<dd>
297<p>Parses an XML document from a string constant.  This function can
298be used to embed &quot;XML literals&quot; in Python code.</p>
299<dl>
300<dt><i>source</i></dt>
301<dd>
302A string containing XML data.</dd>
303<dt><i>parser</i></dt>
304<dd>
305An optional parser instance.  If not given, the
306    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
307</dd>
308<dt>Returns:</dt>
309<dd>
310An Element instance.</dd>
311</dl><br />
312</dd>
313<dt><a id='elementtree.ElementTree.XMLID-function' name='elementtree.ElementTree.XMLID-function'><b>XMLID(text, parser=None)</b></a> &rArr; (Element, dictionary) [<a href='#elementtree.ElementTree.XMLID-function'>#</a>]</dt>
314<dd>
315<p>Parses an XML document from a string constant, and also returns
316a dictionary which maps from element id:s to elements.</p>
317<dl>
318<dt><i>source</i></dt>
319<dd>
320A string containing XML data.</dd>
321<dt><i>parser</i></dt>
322<dd>
323An optional parser instance.  If not given, the
324    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
325</dd>
326<dt>Returns:</dt>
327<dd>
328A tuple containing an Element instance and a dictionary.</dd>
329</dl><br />
330</dd>
331<dt><b>XMLParser(html=0, target=None, encoding=None)</b> (class) [<a href='#elementtree.ElementTree.XMLParser-class'>#</a>]</dt>
332<dd>
333<p>Element structure builder for XML source data, based on the
334expat parser.</p>
335<dl>
336<dt><i>target=</i></dt>
337<dd>
338Target object.  If omitted, the builder uses an
339    instance of the standard <a class="link" href="#elementtree.ElementTree.TreeBuilder-class"><b>TreeBuilder</b></a> class.
340</dd>
341<dt><i>html=</i></dt>
342<dd>
343Predefine HTML entities.  This flag is not supported
344    by the current implementation.</dd>
345<dt><i>encoding=</i></dt>
346<dd>
347Optional encoding.  If given, the value overrides
348    the encoding specified in the XML file.</dd>
349</dl><br />
350<p>For more information about this class, see <a href='#elementtree.ElementTree.XMLParser-class'><i>The XMLParser Class</i></a>.</p>
351</dd>
352</dl>
353<h2><a id='elementtree.ElementTree.Element-class' name='elementtree.ElementTree.Element-class'>The Element Class</a></h2>
354<dl>
355<dt><b>Element(tag, attrib={}, **extra)</b> (class) [<a href='#elementtree.ElementTree.Element-class'>#</a>]</dt>
356<dd>
357<p>Element class.  This class defines the Element interface, and
358provides a reference implementation of this interface.
359</p><p>
360The element name, attribute names, and attribute values can be
361either ASCII strings (ordinary Python strings containing only 7-bit
362ASCII characters) or Unicode strings.
363
364</p><dl>
365<dt><i>tag</i></dt>
366<dd>
367The element name.</dd>
368<dt><i>attrib</i></dt>
369<dd>
370An optional dictionary, containing element attributes.</dd>
371<dt><i>**extra</i></dt>
372<dd>
373Additional attributes, given as keyword arguments.</dd>
374</dl><br />
375</dd>
376<dt><a id='elementtree.ElementTree.Element.__delitem__-method' name='elementtree.ElementTree.Element.__delitem__-method'><b>__delitem__(index)</b></a> [<a href='#elementtree.ElementTree.Element.__delitem__-method'>#</a>]</dt>
377<dd>
378<p>Deletes the given subelement, by index.</p>
379<dl>
380<dt><i>index</i></dt>
381<dd>
382What subelement to delete.</dd>
383<dt>Raises <b>IndexError</b>:</dt><dd>
384If the given element does not exist.</dd>
385</dl><br />
386</dd>
387<dt><a id='elementtree.ElementTree.Element.__delslice__-method' name='elementtree.ElementTree.Element.__delslice__-method'><b>__delslice__(start, stop)</b></a> [<a href='#elementtree.ElementTree.Element.__delslice__-method'>#</a>]</dt>
388<dd>
389<p>Deletes a number of subelements.</p>
390<dl>
391<dt><i>start</i></dt>
392<dd>
393The first subelement to delete.</dd>
394<dt><i>stop</i></dt>
395<dd>
396The first subelement to leave in there.</dd>
397</dl><br />
398</dd>
399<dt><a id='elementtree.ElementTree.Element.__getitem__-method' name='elementtree.ElementTree.Element.__getitem__-method'><b>__getitem__(index)</b></a> [<a href='#elementtree.ElementTree.Element.__getitem__-method'>#</a>]</dt>
400<dd>
401<p>Returns the given subelement, by index.</p>
402<dl>
403<dt><i>index</i></dt>
404<dd>
405What subelement to return.</dd>
406<dt>Returns:</dt>
407<dd>
408The given subelement.</dd>
409<dt>Raises <b>IndexError</b>:</dt><dd>
410If the given element does not exist.</dd>
411</dl><br />
412</dd>
413<dt><a id='elementtree.ElementTree.Element.__getslice__-method' name='elementtree.ElementTree.Element.__getslice__-method'><b>__getslice__(start, stop)</b></a> [<a href='#elementtree.ElementTree.Element.__getslice__-method'>#</a>]</dt>
414<dd>
415<p>Returns a list containing subelements in the given range.</p>
416<dl>
417<dt><i>start</i></dt>
418<dd>
419The first subelement to return.</dd>
420<dt><i>stop</i></dt>
421<dd>
422The first subelement that shouldn't be returned.</dd>
423<dt>Returns:</dt>
424<dd>
425A sequence object containing subelements.</dd>
426</dl><br />
427</dd>
428<dt><a id='elementtree.ElementTree.Element.__len__-method' name='elementtree.ElementTree.Element.__len__-method'><b>__len__()</b></a> [<a href='#elementtree.ElementTree.Element.__len__-method'>#</a>]</dt>
429<dd>
430<p>Returns the number of subelements.  Note that this only counts
431full elements; to check if there's any content in an element, you
432have to check both the length and the <b>text</b> attribute.
433
434</p><dl>
435<dt>Returns:</dt>
436<dd>
437The number of subelements.</dd>
438</dl><br />
439</dd>
440<dt><a id='elementtree.ElementTree.Element.__setitem__-method' name='elementtree.ElementTree.Element.__setitem__-method'><b>__setitem__(index, element)</b></a> [<a href='#elementtree.ElementTree.Element.__setitem__-method'>#</a>]</dt>
441<dd>
442<p>Replaces the given subelement, by index.</p>
443<dl>
444<dt><i>index</i></dt>
445<dd>
446What subelement to replace.</dd>
447<dt><i>element</i></dt>
448<dd>
449The new element value.</dd>
450<dt>Raises <b>IndexError</b>:</dt><dd>
451If the given element does not exist.</dd>
452</dl><br />
453</dd>
454<dt><a id='elementtree.ElementTree.Element.__setslice__-method' name='elementtree.ElementTree.Element.__setslice__-method'><b>__setslice__(start, stop, elements)</b></a> [<a href='#elementtree.ElementTree.Element.__setslice__-method'>#</a>]</dt>
455<dd>
456<p>Replaces a number of subelements with elements from a sequence.</p>
457<dl>
458<dt><i>start</i></dt>
459<dd>
460The first subelement to replace.</dd>
461<dt><i>stop</i></dt>
462<dd>
463The first subelement that shouldn't be replaced.</dd>
464<dt><i>elements</i></dt>
465<dd>
466A sequence object with zero or more elements.</dd>
467</dl><br />
468</dd>
469<dt><a id='elementtree.ElementTree.Element.append-method' name='elementtree.ElementTree.Element.append-method'><b>append(element)</b></a> [<a href='#elementtree.ElementTree.Element.append-method'>#</a>]</dt>
470<dd>
471<p>Adds a subelement to the end of this element.  In document order,
472the new element will appear after the last existing subelement (or
473directly after the text, if it's the first subelement), but before
474the end tag for this element.</p>
475<dl>
476<dt><i>element</i></dt>
477<dd>
478The element to add.</dd>
479</dl><br />
480</dd>
481<dt><a id='elementtree.ElementTree.Element.attrib-attribute' name='elementtree.ElementTree.Element.attrib-attribute'><b>attrib</b></a> [<a href='#elementtree.ElementTree.Element.attrib-attribute'>#</a>]</dt>
482<dd>
483<p>(Attribute) Element attribute dictionary.  Where possible, use
484<a class="link" href="#elementtree.ElementTree.Element.get-method"><b>get</b></a>,
485<a class="link" href="#elementtree.ElementTree.Element.set-method"><b>set</b></a>,
486<a class="link" href="#elementtree.ElementTree.Element.keys-method"><b>keys</b></a>, and
487<a class="link" href="#elementtree.ElementTree.Element.items-method"><b>items</b></a> to access
488element attributes.
489</p></dd>
490<dt><a id='elementtree.ElementTree.Element.clear-method' name='elementtree.ElementTree.Element.clear-method'><b>clear()</b></a> [<a href='#elementtree.ElementTree.Element.clear-method'>#</a>]</dt>
491<dd>
492<p>Resets an element.  This function removes all subelements, clears
493all attributes, and sets the <b>text</b> and <b>tail</b> attributes
494to None.
495</p></dd>
496<dt><a id='elementtree.ElementTree.Element.copy-method' name='elementtree.ElementTree.Element.copy-method'><b>copy()</b></a> [<a href='#elementtree.ElementTree.Element.copy-method'>#</a>]</dt>
497<dd>
498<p>(Experimental) Copies the current element.  This creates a
499shallow copy; subelements will be shared with the original tree.</p>
500<dl>
501<dt>Returns:</dt>
502<dd>
503A new element instance.</dd>
504</dl><br />
505</dd>
506<dt><a id='elementtree.ElementTree.Element.extend-method' name='elementtree.ElementTree.Element.extend-method'><b>extend(elements)</b></a> [<a href='#elementtree.ElementTree.Element.extend-method'>#</a>]</dt>
507<dd>
508<p>Appends subelements from a sequence.</p>
509<dl>
510<dt><i>elements</i></dt>
511<dd>
512A sequence object with zero or more elements.</dd>
513</dl><br />
514</dd>
515<dt><a id='elementtree.ElementTree.Element.find-method' name='elementtree.ElementTree.Element.find-method'><b>find(path, namespaces=None)</b></a> &rArr; Element or None [<a href='#elementtree.ElementTree.Element.find-method'>#</a>]</dt>
516<dd>
517<p>Finds the first matching subelement, by tag name or path.</p>
518<dl>
519<dt><i>path</i></dt>
520<dd>
521What element to look for.</dd>
522<dt><i>namespaces=</i></dt>
523<dd>
524Optional namespace prefix map.</dd>
525<dt>Returns:</dt>
526<dd>
527The first matching element, or None if no element was found.</dd>
528</dl><br />
529</dd>
530<dt><a id='elementtree.ElementTree.Element.findall-method' name='elementtree.ElementTree.Element.findall-method'><b>findall(path, namespaces=None)</b></a> &rArr; list of Element instances [<a href='#elementtree.ElementTree.Element.findall-method'>#</a>]</dt>
531<dd>
532<p>Finds all matching subelements, by tag name or path.</p>
533<dl>
534<dt><i>path</i></dt>
535<dd>
536What element to look for.</dd>
537<dt><i>namespaces=</i></dt>
538<dd>
539Optional namespace prefix map.</dd>
540<dt>Returns:</dt>
541<dd>
542A list or other sequence containing all matching elements,
543   in document order.</dd>
544</dl><br />
545</dd>
546<dt><a id='elementtree.ElementTree.Element.findtext-method' name='elementtree.ElementTree.Element.findtext-method'><b>findtext(path, default=None, namespaces=None)</b></a> &rArr; string [<a href='#elementtree.ElementTree.Element.findtext-method'>#</a>]</dt>
547<dd>
548<p>Finds text for the first matching subelement, by tag name or path.</p>
549<dl>
550<dt><i>path</i></dt>
551<dd>
552What element to look for.</dd>
553<dt><i>default</i></dt>
554<dd>
555What to return if the element was not found.</dd>
556<dt><i>namespaces=</i></dt>
557<dd>
558Optional namespace prefix map.</dd>
559<dt>Returns:</dt>
560<dd>
561The text content of the first matching element, or the
562    default value no element was found.  Note that if the element
563    has is found, but has no text content, this method returns an
564    empty string.</dd>
565</dl><br />
566</dd>
567<dt><a id='elementtree.ElementTree.Element.get-method' name='elementtree.ElementTree.Element.get-method'><b>get(key, default=None)</b></a> &rArr; string or None [<a href='#elementtree.ElementTree.Element.get-method'>#</a>]</dt>
568<dd>
569<p>Gets an element attribute.  Equivalent to <b>attrib.get</b>, but
570some implementations may handle this a bit more efficiently.
571
572</p><dl>
573<dt><i>key</i></dt>
574<dd>
575What attribute to look for.</dd>
576<dt><i>default</i></dt>
577<dd>
578What to return if the attribute was not found.</dd>
579<dt>Returns:</dt>
580<dd>
581The attribute value, or the default value, if the
582    attribute was not found.</dd>
583</dl><br />
584</dd>
585<dt><a id='elementtree.ElementTree.Element.getchildren-method' name='elementtree.ElementTree.Element.getchildren-method'><b>getchildren()</b></a> &rArr; list of Element instances [<a href='#elementtree.ElementTree.Element.getchildren-method'>#</a>]</dt>
586<dd>
587<p>(Deprecated) Returns all subelements.  The elements are returned
588in document order.</p>
589<dl>
590<dt>Returns:</dt>
591<dd>
592A list of subelements.</dd>
593</dl><br />
594</dd>
595<dt><a id='elementtree.ElementTree.Element.insert-method' name='elementtree.ElementTree.Element.insert-method'><b>insert(index, element)</b></a> [<a href='#elementtree.ElementTree.Element.insert-method'>#</a>]</dt>
596<dd>
597<p>Inserts a subelement at the given position in this element.</p>
598<dl>
599<dt><i>index</i></dt>
600<dd>
601Where to insert the new subelement.</dd>
602</dl><br />
603</dd>
604<dt><a id='elementtree.ElementTree.Element.items-method' name='elementtree.ElementTree.Element.items-method'><b>items()</b></a> &rArr; list of (string, string) tuples [<a href='#elementtree.ElementTree.Element.items-method'>#</a>]</dt>
605<dd>
606<p>Gets element attributes, as a sequence.  The attributes are
607returned in an arbitrary order.  Equivalent to <b>attrib.items()</b>.
608
609</p><dl>
610<dt>Returns:</dt>
611<dd>
612A list of (name, value) tuples for all attributes.</dd>
613</dl><br />
614</dd>
615<dt><a id='elementtree.ElementTree.Element.iter-method' name='elementtree.ElementTree.Element.iter-method'><b>iter(tag=None)</b></a> &rArr; iterator [<a href='#elementtree.ElementTree.Element.iter-method'>#</a>]</dt>
616<dd>
617<p>Creates a tree iterator.  The iterator loops over this element
618and all subelements, in document order, and returns all elements
619with a matching tag.
620</p><p>
621If the tree structure is modified during iteration, new or removed
622elements may or may not be included.  To get a stable set, use the
623list() function on the iterator, and loop over the resulting list.
624
625</p><dl>
626<dt><i>tag</i></dt>
627<dd>
628What tags to look for (default is to return all elements).</dd>
629<dt>Returns:</dt>
630<dd>
631An iterator containing all the matching elements.</dd>
632</dl><br />
633</dd>
634<dt><a id='elementtree.ElementTree.Element.iterfind-method' name='elementtree.ElementTree.Element.iterfind-method'><b>iterfind(path, namespaces=None)</b></a> &rArr; a generated sequence of Element instances [<a href='#elementtree.ElementTree.Element.iterfind-method'>#</a>]</dt>
635<dd>
636<p>Finds all matching subelements, by tag name or path.</p>
637<dl>
638<dt><i>path</i></dt>
639<dd>
640What element to look for.</dd>
641<dt><i>namespaces=</i></dt>
642<dd>
643Optional namespace prefix map.</dd>
644<dt>Returns:</dt>
645<dd>
646An iterator or sequence containing all matching elements,
647   in document order.</dd>
648</dl><br />
649</dd>
650<dt><a id='elementtree.ElementTree.Element.itertext-method' name='elementtree.ElementTree.Element.itertext-method'><b>itertext()</b></a> &rArr; iterator [<a href='#elementtree.ElementTree.Element.itertext-method'>#</a>]</dt>
651<dd>
652<p>Creates a text iterator.  The iterator loops over this element
653and all subelements, in document order, and returns all inner
654text.</p>
655<dl>
656<dt>Returns:</dt>
657<dd>
658An iterator containing all inner text.</dd>
659</dl><br />
660</dd>
661<dt><a id='elementtree.ElementTree.Element.keys-method' name='elementtree.ElementTree.Element.keys-method'><b>keys()</b></a> &rArr; list of strings [<a href='#elementtree.ElementTree.Element.keys-method'>#</a>]</dt>
662<dd>
663<p>Gets a list of attribute names.  The names are returned in an
664arbitrary order (just like for an ordinary Python dictionary).
665Equivalent to <b>attrib.keys()</b>.
666
667</p><dl>
668<dt>Returns:</dt>
669<dd>
670A list of element attribute names.</dd>
671</dl><br />
672</dd>
673<dt><a id='elementtree.ElementTree.Element.makeelement-method' name='elementtree.ElementTree.Element.makeelement-method'><b>makeelement(tag, attrib)</b></a> [<a href='#elementtree.ElementTree.Element.makeelement-method'>#</a>]</dt>
674<dd>
675<p>Creates a new element object of the same type as this element.</p>
676<dl>
677<dt><i>tag</i></dt>
678<dd>
679Element tag.</dd>
680<dt><i>attrib</i></dt>
681<dd>
682Element attributes, given as a dictionary.</dd>
683<dt>Returns:</dt>
684<dd>
685A new element instance.</dd>
686</dl><br />
687</dd>
688<dt><a id='elementtree.ElementTree.Element.remove-method' name='elementtree.ElementTree.Element.remove-method'><b>remove(element)</b></a> [<a href='#elementtree.ElementTree.Element.remove-method'>#</a>]</dt>
689<dd>
690<p>Removes a matching subelement.  Unlike the <b>find</b> methods,
691this method compares elements based on identity, not on tag
692value or contents.  To remove subelements by other means, the
693easiest way is often to use a list comprehension to select what
694elements to keep, and use slice assignment to update the parent
695element.
696
697</p><dl>
698<dt><i>element</i></dt>
699<dd>
700What element to remove.</dd>
701<dt>Raises <b>ValueError</b>:</dt><dd>
702If a matching element could not be found.</dd>
703</dl><br />
704</dd>
705<dt><a id='elementtree.ElementTree.Element.set-method' name='elementtree.ElementTree.Element.set-method'><b>set(key, value)</b></a> [<a href='#elementtree.ElementTree.Element.set-method'>#</a>]</dt>
706<dd>
707<p>Sets an element attribute.  Equivalent to <b>attrib[key] = value</b>,
708but some implementations may handle this a bit more efficiently.
709
710</p><dl>
711<dt><i>key</i></dt>
712<dd>
713What attribute to set.</dd>
714<dt><i>value</i></dt>
715<dd>
716The attribute value.</dd>
717</dl><br />
718</dd>
719<dt><a id='elementtree.ElementTree.Element.tag-attribute' name='elementtree.ElementTree.Element.tag-attribute'><b>tag</b></a> [<a href='#elementtree.ElementTree.Element.tag-attribute'>#</a>]</dt>
720<dd>
721<p>(Attribute) Element tag.</p>
722</dd>
723<dt><a id='elementtree.ElementTree.Element.tail-attribute' name='elementtree.ElementTree.Element.tail-attribute'><b>tail</b></a> [<a href='#elementtree.ElementTree.Element.tail-attribute'>#</a>]</dt>
724<dd>
725<p>(Attribute) Text after this element's end tag, but before the
726next sibling element's start tag.  This is either a string or
727the value None.  Note that if there was no text, this attribute
728may be either None or an empty string, depending on the parser.</p>
729</dd>
730<dt><a id='elementtree.ElementTree.Element.text-attribute' name='elementtree.ElementTree.Element.text-attribute'><b>text</b></a> [<a href='#elementtree.ElementTree.Element.text-attribute'>#</a>]</dt>
731<dd>
732<p>(Attribute) Text before first subelement.  This is either a
733string or the value None.  Note that if there was no text, this
734attribute may be either None or an empty string, depending on
735the parser.</p>
736</dd>
737</dl>
738<h2><a id='elementtree.ElementTree.ElementTree-class' name='elementtree.ElementTree.ElementTree-class'>The ElementTree Class</a></h2>
739<dl>
740<dt><b>ElementTree(element=None, file=None)</b> (class) [<a href='#elementtree.ElementTree.ElementTree-class'>#</a>]</dt>
741<dd>
742<p>ElementTree wrapper class.  This class represents an entire element
743hierarchy, and adds some extra support for serialization to and from
744standard XML.</p>
745<dl>
746<dt><i>element</i></dt>
747<dd>
748Optional root element.</dd>
749<dt><i>file=</i></dt>
750<dd>
751Optional file handle or file name.  If given, the
752    tree is initialized with the contents of this XML file.</dd>
753</dl><br />
754</dd>
755<dt><a id='elementtree.ElementTree.ElementTree._setroot-method' name='elementtree.ElementTree.ElementTree._setroot-method'><b>_setroot(element)</b></a> [<a href='#elementtree.ElementTree.ElementTree._setroot-method'>#</a>]</dt>
756<dd>
757<p>Replaces the root element for this tree.  This discards the
758current contents of the tree, and replaces it with the given
759element.  Use with care.</p>
760<dl>
761<dt><i>element</i></dt>
762<dd>
763An element instance.</dd>
764</dl><br />
765</dd>
766<dt><a id='elementtree.ElementTree.ElementTree.find-method' name='elementtree.ElementTree.ElementTree.find-method'><b>find(path, namespaces=None)</b></a> &rArr; Element or None [<a href='#elementtree.ElementTree.ElementTree.find-method'>#</a>]</dt>
767<dd>
768<p>Finds the first toplevel element with given tag.
769Same as getroot().find(path).</p>
770<dl>
771<dt><i>path</i></dt>
772<dd>
773What element to look for.</dd>
774<dt><i>namespaces=</i></dt>
775<dd>
776Optional namespace prefix map.</dd>
777<dt>Returns:</dt>
778<dd>
779The first matching element, or None if no element was found.</dd>
780</dl><br />
781</dd>
782<dt><a id='elementtree.ElementTree.ElementTree.findall-method' name='elementtree.ElementTree.ElementTree.findall-method'><b>findall(path, namespaces=None)</b></a> &rArr; list of Element instances [<a href='#elementtree.ElementTree.ElementTree.findall-method'>#</a>]</dt>
783<dd>
784<p>Finds all toplevel elements with the given tag.
785Same as getroot().findall(path).</p>
786<dl>
787<dt><i>path</i></dt>
788<dd>
789What element to look for.</dd>
790<dt><i>namespaces=</i></dt>
791<dd>
792Optional namespace prefix map.</dd>
793<dt>Returns:</dt>
794<dd>
795A list or iterator containing all matching elements,
796   in document order.</dd>
797</dl><br />
798</dd>
799<dt><a id='elementtree.ElementTree.ElementTree.findtext-method' name='elementtree.ElementTree.ElementTree.findtext-method'><b>findtext(path, default=None, namespaces=None)</b></a> &rArr; string [<a href='#elementtree.ElementTree.ElementTree.findtext-method'>#</a>]</dt>
800<dd>
801<p>Finds the element text for the first toplevel element with given
802tag.  Same as getroot().findtext(path).</p>
803<dl>
804<dt><i>path</i></dt>
805<dd>
806What toplevel element to look for.</dd>
807<dt><i>default</i></dt>
808<dd>
809What to return if the element was not found.</dd>
810<dt><i>namespaces=</i></dt>
811<dd>
812Optional namespace prefix map.</dd>
813<dt>Returns:</dt>
814<dd>
815The text content of the first matching element, or the
816    default value no element was found.  Note that if the element
817    has is found, but has no text content, this method returns an
818    empty string.</dd>
819</dl><br />
820</dd>
821<dt><a id='elementtree.ElementTree.ElementTree.getroot-method' name='elementtree.ElementTree.ElementTree.getroot-method'><b>getroot()</b></a> &rArr; Element [<a href='#elementtree.ElementTree.ElementTree.getroot-method'>#</a>]</dt>
822<dd>
823<p>Gets the root element for this tree.</p>
824<dl>
825<dt>Returns:</dt>
826<dd>
827An element instance.</dd>
828</dl><br />
829</dd>
830<dt><a id='elementtree.ElementTree.ElementTree.iter-method' name='elementtree.ElementTree.ElementTree.iter-method'><b>iter(tag=None)</b></a> &rArr; iterator [<a href='#elementtree.ElementTree.ElementTree.iter-method'>#</a>]</dt>
831<dd>
832<p>Creates a tree iterator for the root element.  The iterator loops
833over all elements in this tree, in document order.</p>
834<dl>
835<dt><i>tag</i></dt>
836<dd>
837What tags to look for (default is to return all elements)</dd>
838<dt>Returns:</dt>
839<dd>
840An iterator.</dd>
841</dl><br />
842</dd>
843<dt><a id='elementtree.ElementTree.ElementTree.parse-method' name='elementtree.ElementTree.ElementTree.parse-method'><b>parse(source, parser=None)</b></a> &rArr; Element [<a href='#elementtree.ElementTree.ElementTree.parse-method'>#</a>]</dt>
844<dd>
845<p>Loads an external XML document into this element tree.</p>
846<dl>
847<dt><i>source</i></dt>
848<dd>
849A file name or file object.  If a file object is
850    given, it only has to implement a <b>read(n)</b> method.
851</dd>
852<dt><i>parser=</i></dt>
853<dd>
854An optional parser instance.  If not given, the
855    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
856</dd>
857<dt>Returns:</dt>
858<dd>
859The document root element.</dd>
860<dt>Raises <b>ParseError</b>:</dt><dd>
861If the parser fails to parse the document.</dd>
862</dl><br />
863</dd>
864<dt><a id='elementtree.ElementTree.ElementTree.write-method' name='elementtree.ElementTree.ElementTree.write-method'><b>write(file, **options)</b></a> [<a href='#elementtree.ElementTree.ElementTree.write-method'>#</a>]</dt>
865<dd>
866<p>Writes the element tree to a file, as XML.</p>
867<dl>
868<dt><i>file</i></dt>
869<dd>
870A file name, or a file object opened for writing.</dd>
871<dt><i>**options</i></dt>
872<dd>
873Options, given as keyword arguments.</dd>
874<dt><i>encoding=</i></dt>
875<dd>
876Optional output encoding (default is US-ASCII).</dd>
877<dt><i>method=</i></dt>
878<dd>
879Optional output method (&quot;xml&quot;, &quot;html&quot;, &quot;text&quot; or
880    &quot;c14n&quot;; default is &quot;xml&quot;.</dd>
881<dt><i>xml_declaration=</i></dt>
882<dd>
883Controls if an XML declaration should
884    be added to the file.  Use False for never, True for always,
885    None for only if not US-ASCII or UTF-8.  None is default.</dd>
886</dl><br />
887</dd>
888</dl>
889<h2><a id='elementtree.ElementTree.ParseError-class' name='elementtree.ElementTree.ParseError-class'>The ParseError Class</a></h2>
890<dl>
891<dt><b>ParseError</b> (class)  [<a href='#elementtree.ElementTree.ParseError-class'>#</a>]</dt>
892<dd>
893<p>Parser error.  This is a subclass of <b>SyntaxError</b>.
894</p><p>
895In addition to the exception value, an exception instance contains a
896specific exception code in the <b>code</b> attribute, and the line and
897column of the error in the <b>position</b> attribute.
898</p></dd>
899</dl>
900<h2><a id='elementtree.ElementTree.QName-class' name='elementtree.ElementTree.QName-class'>The QName Class</a></h2>
901<dl>
902<dt><b>QName(text_or_uri, tag=None)</b> (class) [<a href='#elementtree.ElementTree.QName-class'>#</a>]</dt>
903<dd>
904<p>QName wrapper.  This can be used to wrap a QName attribute value, in
905order to get proper namespace handling on output.</p>
906<dl>
907<dt><i>text</i></dt>
908<dd>
909A string containing the QName value, in the form {uri}local,
910    or, if the tag argument is given, the URI part of a QName.</dd>
911<dt><i>tag</i></dt>
912<dd>
913Optional tag.  If given, the first argument is interpreted as
914    an URI, and this argument is interpreted as a local name.</dd>
915<dt>Returns:</dt>
916<dd>
917An opaque object, representing the QName.</dd>
918</dl><br />
919</dd>
920</dl>
921<h2><a id='elementtree.ElementTree.TreeBuilder-class' name='elementtree.ElementTree.TreeBuilder-class'>The TreeBuilder Class</a></h2>
922<dl>
923<dt><b>TreeBuilder(element_factory=None)</b> (class) [<a href='#elementtree.ElementTree.TreeBuilder-class'>#</a>]</dt>
924<dd>
925<p>Generic element structure builder.  This builder converts a sequence
926of <a class="link" href="#elementtree.ElementTree.TreeBuilder.start-method"><b>start</b></a>, <a class="link" href="#elementtree.ElementTree.TreeBuilder.data-method"><b>data</b></a>, and <a class="link" href="#elementtree.ElementTree.TreeBuilder.end-method"><b>end</b></a> method calls to a well-formed element structure.
927</p><p>
928You can use this class to build an element structure using a custom XML
929parser, or a parser for some other XML-like format.
930
931</p><dl>
932<dt><i>element_factory</i></dt>
933<dd>
934Optional element factory.  This factory
935   is called to create new Element instances, as necessary.</dd>
936</dl><br />
937</dd>
938<dt><a id='elementtree.ElementTree.TreeBuilder.close-method' name='elementtree.ElementTree.TreeBuilder.close-method'><b>close()</b></a> &rArr; Element [<a href='#elementtree.ElementTree.TreeBuilder.close-method'>#</a>]</dt>
939<dd>
940<p>Flushes the builder buffers, and returns the toplevel document
941element.</p>
942<dl>
943<dt>Returns:</dt>
944<dd>
945An Element instance.</dd>
946</dl><br />
947</dd>
948<dt><a id='elementtree.ElementTree.TreeBuilder.data-method' name='elementtree.ElementTree.TreeBuilder.data-method'><b>data(data)</b></a> [<a href='#elementtree.ElementTree.TreeBuilder.data-method'>#</a>]</dt>
949<dd>
950<p>Adds text to the current element.</p>
951<dl>
952<dt><i>data</i></dt>
953<dd>
954A string.  This should be either an 8-bit string
955   containing ASCII text, or a Unicode string.</dd>
956</dl><br />
957</dd>
958<dt><a id='elementtree.ElementTree.TreeBuilder.end-method' name='elementtree.ElementTree.TreeBuilder.end-method'><b>end(tag)</b></a> &rArr; Element [<a href='#elementtree.ElementTree.TreeBuilder.end-method'>#</a>]</dt>
959<dd>
960<p>Closes the current element.</p>
961<dl>
962<dt><i>tag</i></dt>
963<dd>
964The element name.</dd>
965<dt>Returns:</dt>
966<dd>
967The closed element.</dd>
968</dl><br />
969</dd>
970<dt><a id='elementtree.ElementTree.TreeBuilder.start-method' name='elementtree.ElementTree.TreeBuilder.start-method'><b>start(tag, attrs)</b></a> &rArr; Element [<a href='#elementtree.ElementTree.TreeBuilder.start-method'>#</a>]</dt>
971<dd>
972<p>Opens a new element.</p>
973<dl>
974<dt><i>tag</i></dt>
975<dd>
976The element name.</dd>
977<dt><i>attrib</i></dt>
978<dd>
979A dictionary containing element attributes.</dd>
980<dt>Returns:</dt>
981<dd>
982The opened element.</dd>
983</dl><br />
984</dd>
985</dl>
986<h2><a id='elementtree.ElementTree.XMLParser-class' name='elementtree.ElementTree.XMLParser-class'>The XMLParser Class</a></h2>
987<dl>
988<dt><b>XMLParser(html=0, target=None, encoding=None)</b> (class) [<a href='#elementtree.ElementTree.XMLParser-class'>#</a>]</dt>
989<dd>
990<p>Element structure builder for XML source data, based on the
991<b>expat</b> parser.
992
993</p><dl>
994<dt><i>target=</i></dt>
995<dd>
996Target object.  If omitted, the builder uses an
997    instance of the standard <a class="link" href="#elementtree.ElementTree.TreeBuilder-class"><b>TreeBuilder</b></a> class.
998</dd>
999<dt><i>html=</i></dt>
1000<dd>
1001Predefine HTML entities.  This flag is not supported
1002    by the current implementation.</dd>
1003<dt><i>encoding=</i></dt>
1004<dd>
1005Optional encoding.  If given, the value overrides
1006    the encoding specified in the XML file.</dd>
1007</dl><br />
1008</dd>
1009<dt><a id='elementtree.ElementTree.XMLParser.close-method' name='elementtree.ElementTree.XMLParser.close-method'><b>close()</b></a> &rArr; Element [<a href='#elementtree.ElementTree.XMLParser.close-method'>#</a>]</dt>
1010<dd>
1011<p>Finishes feeding data to the parser.</p>
1012<dl>
1013<dt>Returns:</dt>
1014<dd>
1015An element structure.</dd>
1016</dl><br />
1017</dd>
1018<dt><a id='elementtree.ElementTree.XMLParser.feed-method' name='elementtree.ElementTree.XMLParser.feed-method'><b>feed(data)</b></a> [<a href='#elementtree.ElementTree.XMLParser.feed-method'>#</a>]</dt>
1019<dd>
1020<p>Feeds data to the parser.</p>
1021<dl>
1022<dt><i>data</i></dt>
1023<dd>
1024Encoded data.</dd>
1025</dl><br />
1026</dd>
1027</dl>
1028</body></html>
Note: See TracBrowser for help on using the repository browser.