source: exist/trunk/python/elementtree-1.3/docs/pythondoc-elementtree.ElementTree.html @ 3150

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/exist/trunk/python/elementtree-1.3/docs/pythondoc-elementtree.ElementTree.html@3150
Revision 3150, 36.3 KB checked in by lawrence, 12 years ago (diff)

woops, we didn't include elementtree itself.

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><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>
175<dd>
176<p>PI element factory.  This factory function creates a special element
177that will be serialized as an XML processing instruction by the standard
178serializer.</p>
179<dl>
180<dt><i>target</i></dt>
181<dd>
182A string containing the PI target.</dd>
183<dt><i>text</i></dt>
184<dd>
185A string containing the PI contents, if any.</dd>
186<dt>Returns:</dt>
187<dd>
188An element instance, representing a PI.</dd>
189</dl><br />
190</dd>
191<dt><b>QName(text_or_uri, tag=None)</b> (class) [<a href='#elementtree.ElementTree.QName-class'>#</a>]</dt>
192<dd>
193<p>QName wrapper.</p>
194<dl>
195<dt><i>text</i></dt>
196<dd>
197A string containing the QName value, in the form {uri}local,
198    or, if the tag argument is given, the URI part of a QName.</dd>
199<dt><i>tag</i></dt>
200<dd>
201Optional tag.  If given, the first argument is interpreted as
202    an URI, and this argument is interpreted as a local name.</dd>
203<dt>Returns:</dt>
204<dd>
205An opaque object, representing the QName.</dd>
206</dl><br />
207<p>For more information about this class, see <a href='#elementtree.ElementTree.QName-class'><i>The QName Class</i></a>.</p>
208</dd>
209<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>
210<dd>
211<p>Registers a namespace prefix.  The registry is global, and any
212existing mapping for either the given prefix or the namespace URI
213will be removed.</p>
214<dl>
215<dt><i>prefix</i></dt>
216<dd>
217Namespace prefix.</dd>
218<dt><i>uri</i></dt>
219<dd>
220Namespace uri.  Tags and attributes in this namespace
221    will be serialized with the given prefix, if at all possible.</dd>
222</dl><br />
223</dd>
224<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>
225<dd>
226<p>Subelement factory.  This function creates an element instance, and
227appends it to an existing element.
228</p><p>
229The element name, attribute names, and attribute values can be
230either 8-bit ASCII strings or Unicode strings.
231
232</p><dl>
233<dt><i>parent</i></dt>
234<dd>
235The parent element.</dd>
236<dt><i>tag</i></dt>
237<dd>
238The subelement name.</dd>
239<dt><i>attrib</i></dt>
240<dd>
241An optional dictionary, containing element attributes.</dd>
242<dt><i>**extra</i></dt>
243<dd>
244Additional attributes, given as keyword arguments.</dd>
245<dt>Returns:</dt>
246<dd>
247An element instance.</dd>
248</dl><br />
249</dd>
250<dt><a id='elementtree.ElementTree.tostring-function' name='elementtree.ElementTree.tostring-function'><b>tostring(element, encoding=None)</b></a> &rArr; string [<a href='#elementtree.ElementTree.tostring-function'>#</a>]</dt>
251<dd>
252<p>Generates a string representation of an XML element, including all
253subelements.</p>
254<dl>
255<dt><i>element</i></dt>
256<dd>
257An Element instance.</dd>
258<dt>Returns:</dt>
259<dd>
260An encoded string containing the XML data.</dd>
261</dl><br />
262</dd>
263<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>
264<dd>
265<p>Generates a string representation of an XML element, including all
266subelements.  The string is returned as a sequence of string fragments.</p>
267<dl>
268<dt><i>element</i></dt>
269<dd>
270An Element instance.</dd>
271<dt>Returns:</dt>
272<dd>
273A sequence object containing the XML data.</dd>
274</dl><br />
275</dd>
276<dt><b>TreeBuilder(element_factory=None)</b> (class) [<a href='#elementtree.ElementTree.TreeBuilder-class'>#</a>]</dt>
277<dd>
278<p>Generic element structure builder.</p>
279<dl>
280<dt><i>element_factory</i></dt>
281<dd>
282Optional element factory.  This factory
283   is called to create new Element instances, as necessary.</dd>
284</dl><br />
285<p>For more information about this class, see <a href='#elementtree.ElementTree.TreeBuilder-class'><i>The TreeBuilder Class</i></a>.</p>
286</dd>
287<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>
288<dd>
289<p>Parses an XML document from a string constant.  This function can
290be used to embed &quot;XML literals&quot; in Python code.</p>
291<dl>
292<dt><i>source</i></dt>
293<dd>
294A string containing XML data.</dd>
295<dt><i>parser</i></dt>
296<dd>
297An optional parser instance.  If not given, the
298    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
299</dd>
300<dt>Returns:</dt>
301<dd>
302An Element instance.</dd>
303</dl><br />
304</dd>
305<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>
306<dd>
307<p>Parses an XML document from a string constant, and also returns
308a dictionary which maps from element id:s to elements.</p>
309<dl>
310<dt><i>source</i></dt>
311<dd>
312A string containing XML data.</dd>
313<dt><i>parser</i></dt>
314<dd>
315An optional parser instance.  If not given, the
316    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
317</dd>
318<dt>Returns:</dt>
319<dd>
320A tuple containing an Element instance and a dictionary.</dd>
321</dl><br />
322</dd>
323<dt><b>XMLParser(html=0, target=None, encoding=None)</b> (class) [<a href='#elementtree.ElementTree.XMLParser-class'>#</a>]</dt>
324<dd>
325<p>Element structure builder for XML source data, based on the
326expat parser.</p>
327<dl>
328<dt><i>target=</i></dt>
329<dd>
330Target object.  If omitted, the builder uses an
331    instance of the standard <a class="link" href="#elementtree.ElementTree.TreeBuilder-class"><b>TreeBuilder</b></a> class.
332</dd>
333<dt><i>html=</i></dt>
334<dd>
335Predefine HTML entities.  This flag is not supported
336    by the current implementation.</dd>
337<dt><i>encoding=</i></dt>
338<dd>
339Optional encoding.  If given, the value overrides
340    the encoding specified in the XML file.</dd>
341</dl><br />
342<p>For more information about this class, see <a href='#elementtree.ElementTree.XMLParser-class'><i>The XMLParser Class</i></a>.</p>
343</dd>
344</dl>
345<h2><a id='elementtree.ElementTree.Element-class' name='elementtree.ElementTree.Element-class'>The Element Class</a></h2>
346<dl>
347<dt><b>Element(tag, attrib={}, **extra)</b> (class) [<a href='#elementtree.ElementTree.Element-class'>#</a>]</dt>
348<dd>
349<p>Element class.  This class defines the Element interface, and
350provides a reference implementation of this interface.
351</p><p>
352The element name, attribute names, and attribute values can be
353either 8-bit ASCII strings or Unicode strings.
354
355</p><dl>
356<dt><i>tag</i></dt>
357<dd>
358The element name.</dd>
359<dt><i>attrib</i></dt>
360<dd>
361An optional dictionary, containing element attributes.</dd>
362<dt><i>**extra</i></dt>
363<dd>
364Additional attributes, given as keyword arguments.</dd>
365</dl><br />
366</dd>
367<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>
368<dd>
369<p>Deletes the given subelement.</p>
370<dl>
371<dt><i>index</i></dt>
372<dd>
373What subelement to delete.</dd>
374<dt>Raises <b>IndexError</b>:</dt><dd>
375If the given element does not exist.</dd>
376</dl><br />
377</dd>
378<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>
379<dd>
380<p>Deletes a number of subelements.</p>
381<dl>
382<dt><i>start</i></dt>
383<dd>
384The first subelement to delete.</dd>
385<dt><i>stop</i></dt>
386<dd>
387The first subelement to leave in there.</dd>
388</dl><br />
389</dd>
390<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>
391<dd>
392<p>Returns the given subelement.</p>
393<dl>
394<dt><i>index</i></dt>
395<dd>
396What subelement to return.</dd>
397<dt>Returns:</dt>
398<dd>
399The given subelement.</dd>
400<dt>Raises <b>IndexError</b>:</dt><dd>
401If the given element does not exist.</dd>
402</dl><br />
403</dd>
404<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>
405<dd>
406<p>Returns a list containing subelements in the given range.</p>
407<dl>
408<dt><i>start</i></dt>
409<dd>
410The first subelement to return.</dd>
411<dt><i>stop</i></dt>
412<dd>
413The first subelement that shouldn't be returned.</dd>
414<dt>Returns:</dt>
415<dd>
416A sequence object containing subelements.</dd>
417</dl><br />
418</dd>
419<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>
420<dd>
421<p>Returns the number of subelements.</p>
422<dl>
423<dt>Returns:</dt>
424<dd>
425The number of subelements.</dd>
426</dl><br />
427</dd>
428<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>
429<dd>
430<p>Replaces the given subelement.</p>
431<dl>
432<dt><i>index</i></dt>
433<dd>
434What subelement to replace.</dd>
435<dt><i>element</i></dt>
436<dd>
437The new element value.</dd>
438<dt>Raises <b>IndexError</b>:</dt><dd>
439If the given element does not exist.</dd>
440<dt>Raises <b>AssertionError</b>:</dt><dd>
441If element is not a valid object.</dd>
442</dl><br />
443</dd>
444<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>
445<dd>
446<p>Replaces a number of subelements with elements from a sequence.</p>
447<dl>
448<dt><i>start</i></dt>
449<dd>
450The first subelement to replace.</dd>
451<dt><i>stop</i></dt>
452<dd>
453The first subelement that shouldn't be replaced.</dd>
454<dt><i>elements</i></dt>
455<dd>
456A sequence object with zero or more elements.</dd>
457<dt>Raises <b>AssertionError</b>:</dt><dd>
458If a sequence member is not a valid object.</dd>
459</dl><br />
460</dd>
461<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>
462<dd>
463<p>Adds a subelement to the end of this element.</p>
464<dl>
465<dt><i>element</i></dt>
466<dd>
467The element to add.</dd>
468<dt>Raises <b>AssertionError</b>:</dt><dd>
469If a sequence member is not a valid object.</dd>
470</dl><br />
471</dd>
472<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>
473<dd>
474<p>(Attribute) Element attribute dictionary.  Where possible, use
475<a class="link" href="#elementtree.ElementTree.Element.get-method"><b>get</b></a>,
476<a class="link" href="#elementtree.ElementTree.Element.set-method"><b>set</b></a>,
477<a class="link" href="#elementtree.ElementTree.Element.keys-method"><b>keys</b></a>, and
478<a class="link" href="#elementtree.ElementTree.Element.items-method"><b>items</b></a> to access
479element attributes.
480</p></dd>
481<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>
482<dd>
483<p>Resets an element.  This function removes all subelements, clears
484all attributes, and sets the text and tail attributes to None.</p>
485</dd>
486<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>
487<dd>
488<p>Appends subelements from a sequence.</p>
489<dl>
490<dt><i>elements</i></dt>
491<dd>
492A sequence object with zero or more elements.</dd>
493<dt>Raises <b>AssertionError</b>:</dt><dd>
494If a subelement is not a valid object.</dd>
495</dl><br />
496</dd>
497<dt><a id='elementtree.ElementTree.Element.find-method' name='elementtree.ElementTree.Element.find-method'><b>find(path)</b></a> &rArr; Element or None [<a href='#elementtree.ElementTree.Element.find-method'>#</a>]</dt>
498<dd>
499<p>Finds the first matching subelement, by tag name or path.</p>
500<dl>
501<dt><i>path</i></dt>
502<dd>
503What element to look for.</dd>
504<dt>Returns:</dt>
505<dd>
506The first matching element, or None if no element was found.</dd>
507</dl><br />
508</dd>
509<dt><a id='elementtree.ElementTree.Element.findall-method' name='elementtree.ElementTree.Element.findall-method'><b>findall(path)</b></a> &rArr; list of Element instances [<a href='#elementtree.ElementTree.Element.findall-method'>#</a>]</dt>
510<dd>
511<p>Finds all matching subelements, by tag name or path.</p>
512<dl>
513<dt><i>path</i></dt>
514<dd>
515What element to look for.</dd>
516<dt>Returns:</dt>
517<dd>
518A list or iterator containing all matching elements,
519   in document order.</dd>
520</dl><br />
521</dd>
522<dt><a id='elementtree.ElementTree.Element.findtext-method' name='elementtree.ElementTree.Element.findtext-method'><b>findtext(path, default=None)</b></a> &rArr; string [<a href='#elementtree.ElementTree.Element.findtext-method'>#</a>]</dt>
523<dd>
524<p>Finds text for the first matching subelement, by tag name or path.</p>
525<dl>
526<dt><i>path</i></dt>
527<dd>
528What element to look for.</dd>
529<dt><i>default</i></dt>
530<dd>
531What to return if the element was not found.</dd>
532<dt>Returns:</dt>
533<dd>
534The text content of the first matching element, or the
535    default value no element was found.  Note that if the element
536    has is found, but has no text content, this method returns an
537    empty string.</dd>
538</dl><br />
539</dd>
540<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>
541<dd>
542<p>Gets an element attribute.</p>
543<dl>
544<dt><i>key</i></dt>
545<dd>
546What attribute to look for.</dd>
547<dt><i>default</i></dt>
548<dd>
549What to return if the attribute was not found.</dd>
550<dt>Returns:</dt>
551<dd>
552The attribute value, or the default value, if the
553    attribute was not found.</dd>
554</dl><br />
555</dd>
556<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>
557<dd>
558<p>(Deprecated) Returns all subelements.  The elements are returned
559in document order.</p>
560<dl>
561<dt>Returns:</dt>
562<dd>
563A list of subelements.</dd>
564</dl><br />
565</dd>
566<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>
567<dd>
568<p>Inserts a subelement at the given position in this element.</p>
569<dl>
570<dt><i>index</i></dt>
571<dd>
572Where to insert the new subelement.</dd>
573<dt>Raises <b>AssertionError</b>:</dt><dd>
574If the element is not a valid object.</dd>
575</dl><br />
576</dd>
577<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>
578<dd>
579<p>Gets element attributes, as a sequence.  The attributes are
580returned in an arbitrary order.</p>
581<dl>
582<dt>Returns:</dt>
583<dd>
584A list of (name, value) tuples for all attributes.</dd>
585</dl><br />
586</dd>
587<dt><a id='elementtree.ElementTree.Element.iter-method' name='elementtree.ElementTree.Element.iter-method'><b>iter(tag=None)</b></a> &rArr; list or iterator [<a href='#elementtree.ElementTree.Element.iter-method'>#</a>]</dt>
588<dd>
589<p>Creates a tree iterator.  The iterator loops over this element
590and all subelements, in document order, and returns all elements
591with a matching tag.
592</p><p>
593If the tree structure is modified during iteration, the result
594is undefined.
595
596</p><dl>
597<dt><i>tag</i></dt>
598<dd>
599What tags to look for (default is to return all elements).</dd>
600<dt>Returns:</dt>
601<dd>
602A list or iterator containing all the matching elements.</dd>
603</dl><br />
604</dd>
605<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>
606<dd>
607<p>Gets a list of attribute names.  The names are returned in an
608arbitrary order (just like for an ordinary Python dictionary).</p>
609<dl>
610<dt>Returns:</dt>
611<dd>
612A list of element attribute names.</dd>
613</dl><br />
614</dd>
615<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>
616<dd>
617<p>Creates a new element object of the same type as this element.</p>
618<dl>
619<dt><i>tag</i></dt>
620<dd>
621Element tag.</dd>
622<dt><i>attrib</i></dt>
623<dd>
624Element attributes, given as a dictionary.</dd>
625<dt>Returns:</dt>
626<dd>
627A new element instance.</dd>
628</dl><br />
629</dd>
630<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>
631<dd>
632<p>Removes a matching subelement.  Unlike the <b>find</b> methods,
633this method compares elements based on identity, not on tag
634value or contents.
635
636</p><dl>
637<dt><i>element</i></dt>
638<dd>
639What element to remove.</dd>
640<dt>Raises <b>ValueError</b>:</dt><dd>
641If a matching element could not be found.</dd>
642<dt>Raises <b>AssertionError</b>:</dt><dd>
643If the element is not a valid object.</dd>
644</dl><br />
645</dd>
646<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>
647<dd>
648<p>Sets an element attribute.</p>
649<dl>
650<dt><i>key</i></dt>
651<dd>
652What attribute to set.</dd>
653<dt><i>value</i></dt>
654<dd>
655The attribute value.</dd>
656</dl><br />
657</dd>
658<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>
659<dd>
660<p>(Attribute) Element tag.</p>
661</dd>
662<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>
663<dd>
664<p>(Attribute) Text after this element's end tag, but before the
665next sibling element's start tag.  This is either a string or
666the value None, if there was no text.</p>
667</dd>
668<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>
669<dd>
670<p>(Attribute) Text before first subelement.  This is either a
671string or the value None, if there was no text.</p>
672</dd>
673</dl>
674<h2><a id='elementtree.ElementTree.ElementTree-class' name='elementtree.ElementTree.ElementTree-class'>The ElementTree Class</a></h2>
675<dl>
676<dt><b>ElementTree(element=None, file=None)</b> (class) [<a href='#elementtree.ElementTree.ElementTree-class'>#</a>]</dt>
677<dd>
678<p>ElementTree wrapper class.  This class represents an entire element
679hierarchy, and adds some extra support for serialization to and from
680standard XML.</p>
681<dl>
682<dt><i>element</i></dt>
683<dd>
684Optional root element.</dd>
685<dt><i>file=</i></dt>
686<dd>
687Optional file handle or file name.  If given, the
688    tree is initialized with the contents of this XML file.</dd>
689</dl><br />
690</dd>
691<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>
692<dd>
693<p>Replaces the root element for this tree.  This discards the
694current contents of the tree, and replaces it with the given
695element.  Use with care.</p>
696<dl>
697<dt><i>element</i></dt>
698<dd>
699An element instance.</dd>
700</dl><br />
701</dd>
702<dt><a id='elementtree.ElementTree.ElementTree.find-method' name='elementtree.ElementTree.ElementTree.find-method'><b>find(path)</b></a> &rArr; Element or None [<a href='#elementtree.ElementTree.ElementTree.find-method'>#</a>]</dt>
703<dd>
704<p>Finds the first toplevel element with given tag.
705Same as getroot().find(path).</p>
706<dl>
707<dt><i>path</i></dt>
708<dd>
709What element to look for.</dd>
710<dt>Returns:</dt>
711<dd>
712The first matching element, or None if no element was found.</dd>
713</dl><br />
714</dd>
715<dt><a id='elementtree.ElementTree.ElementTree.findall-method' name='elementtree.ElementTree.ElementTree.findall-method'><b>findall(path)</b></a> &rArr; list of Element instances [<a href='#elementtree.ElementTree.ElementTree.findall-method'>#</a>]</dt>
716<dd>
717<p>Finds all toplevel elements with the given tag.
718Same as getroot().findall(path).</p>
719<dl>
720<dt><i>path</i></dt>
721<dd>
722What element to look for.</dd>
723<dt>Returns:</dt>
724<dd>
725A list or iterator containing all matching elements,
726   in document order.</dd>
727</dl><br />
728</dd>
729<dt><a id='elementtree.ElementTree.ElementTree.findtext-method' name='elementtree.ElementTree.ElementTree.findtext-method'><b>findtext(path, default=None)</b></a> &rArr; string [<a href='#elementtree.ElementTree.ElementTree.findtext-method'>#</a>]</dt>
730<dd>
731<p>Finds the element text for the first toplevel element with given
732tag.  Same as getroot().findtext(path).</p>
733<dl>
734<dt><i>path</i></dt>
735<dd>
736What toplevel element to look for.</dd>
737<dt><i>default</i></dt>
738<dd>
739What to return if the element was not found.</dd>
740<dt>Returns:</dt>
741<dd>
742The text content of the first matching element, or the
743    default value no element was found.  Note that if the element
744    has is found, but has no text content, this method returns an
745    empty string.</dd>
746</dl><br />
747</dd>
748<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>
749<dd>
750<p>Gets the root element for this tree.</p>
751<dl>
752<dt>Returns:</dt>
753<dd>
754An element instance.</dd>
755</dl><br />
756</dd>
757<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>
758<dd>
759<p>Creates a tree iterator for the root element.  The iterator loops
760over all elements in this tree, in document order.</p>
761<dl>
762<dt><i>tag</i></dt>
763<dd>
764What tags to look for (default is to return all elements)</dd>
765<dt>Returns:</dt>
766<dd>
767An iterator.</dd>
768</dl><br />
769</dd>
770<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>
771<dd>
772<p>Loads an external XML document into this element tree.</p>
773<dl>
774<dt><i>source</i></dt>
775<dd>
776A file name or file object.</dd>
777<dt><i>parser=</i></dt>
778<dd>
779An optional parser instance.  If not given, the
780    standard <a class="link" href="#elementtree.ElementTree.XMLParser-class"><b>XMLParser</b></a> parser is used.
781</dd>
782<dt>Returns:</dt>
783<dd>
784The document root element.</dd>
785</dl><br />
786</dd>
787<dt><a id='elementtree.ElementTree.ElementTree.write-method' name='elementtree.ElementTree.ElementTree.write-method'><b>write(file, encoding=&quot;us-ascii&quot;, xml_declaration=None)</b></a> [<a href='#elementtree.ElementTree.ElementTree.write-method'>#</a>]</dt>
788<dd>
789<p>Writes the element tree to a file, as XML.</p>
790<dl>
791<dt><i>file</i></dt>
792<dd>
793A file name, or a file object opened for writing.</dd>
794<dt><i>encoding=</i></dt>
795<dd>
796Optional output encoding (default is US-ASCII).</dd>
797<dt><i>xml_declaration=</i></dt>
798<dd>
799Controls if an XML declaration should
800    be added to the file.  Use False for never, True for always,
801    None for only if not US-ASCII or UTF-8.  None is default.</dd>
802</dl><br />
803</dd>
804</dl>
805<h2><a id='elementtree.ElementTree.QName-class' name='elementtree.ElementTree.QName-class'>The QName Class</a></h2>
806<dl>
807<dt><b>QName(text_or_uri, tag=None)</b> (class) [<a href='#elementtree.ElementTree.QName-class'>#</a>]</dt>
808<dd>
809<p>QName wrapper.  This can be used to wrap a QName attribute value, in
810order to get proper namespace handling on output.</p>
811<dl>
812<dt><i>text</i></dt>
813<dd>
814A string containing the QName value, in the form {uri}local,
815    or, if the tag argument is given, the URI part of a QName.</dd>
816<dt><i>tag</i></dt>
817<dd>
818Optional tag.  If given, the first argument is interpreted as
819    an URI, and this argument is interpreted as a local name.</dd>
820<dt>Returns:</dt>
821<dd>
822An opaque object, representing the QName.</dd>
823</dl><br />
824</dd>
825</dl>
826<h2><a id='elementtree.ElementTree.TreeBuilder-class' name='elementtree.ElementTree.TreeBuilder-class'>The TreeBuilder Class</a></h2>
827<dl>
828<dt><b>TreeBuilder(element_factory=None)</b> (class) [<a href='#elementtree.ElementTree.TreeBuilder-class'>#</a>]</dt>
829<dd>
830<p>Generic element structure builder.  This builder converts a sequence
831of <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.
832</p><p>
833You can use this class to build an element structure using a custom XML
834parser, or a parser for some other XML-like format.
835
836</p><dl>
837<dt><i>element_factory</i></dt>
838<dd>
839Optional element factory.  This factory
840   is called to create new Element instances, as necessary.</dd>
841</dl><br />
842</dd>
843<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>
844<dd>
845<p>Flushes the builder buffers, and returns the toplevel document
846element.</p>
847<dl>
848<dt>Returns:</dt>
849<dd>
850An Element instance.</dd>
851</dl><br />
852</dd>
853<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>
854<dd>
855<p>Adds text to the current element.</p>
856<dl>
857<dt><i>data</i></dt>
858<dd>
859A string.  This should be either an 8-bit string
860   containing ASCII text, or a Unicode string.</dd>
861</dl><br />
862</dd>
863<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>
864<dd>
865<p>Closes the current element.</p>
866<dl>
867<dt><i>tag</i></dt>
868<dd>
869The element name.</dd>
870<dt>Returns:</dt>
871<dd>
872The closed element.</dd>
873</dl><br />
874</dd>
875<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>
876<dd>
877<p>Opens a new element.</p>
878<dl>
879<dt><i>tag</i></dt>
880<dd>
881The element name.</dd>
882<dt><i>attrib</i></dt>
883<dd>
884A dictionary containing element attributes.</dd>
885<dt>Returns:</dt>
886<dd>
887The opened element.</dd>
888</dl><br />
889</dd>
890</dl>
891<h2><a id='elementtree.ElementTree.XMLParser-class' name='elementtree.ElementTree.XMLParser-class'>The XMLParser Class</a></h2>
892<dl>
893<dt><b>XMLParser(html=0, target=None, encoding=None)</b> (class) [<a href='#elementtree.ElementTree.XMLParser-class'>#</a>]</dt>
894<dd>
895<p>Element structure builder for XML source data, based on the
896<b>expat</b> parser.
897
898</p><dl>
899<dt><i>target=</i></dt>
900<dd>
901Target object.  If omitted, the builder uses an
902    instance of the standard <a class="link" href="#elementtree.ElementTree.TreeBuilder-class"><b>TreeBuilder</b></a> class.
903</dd>
904<dt><i>html=</i></dt>
905<dd>
906Predefine HTML entities.  This flag is not supported
907    by the current implementation.</dd>
908<dt><i>encoding=</i></dt>
909<dd>
910Optional encoding.  If given, the value overrides
911    the encoding specified in the XML file.</dd>
912</dl><br />
913</dd>
914<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>
915<dd>
916<p>Finishes feeding data to the parser.</p>
917<dl>
918<dt>Returns:</dt>
919<dd>
920An element structure.</dd>
921</dl><br />
922</dd>
923<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>
924<dd>
925<p>Feeds data to the parser.</p>
926<dl>
927<dt><i>data</i></dt>
928<dd>
929Encoded data.</dd>
930</dl><br />
931</dd>
932</dl>
933</body></html>
Note: See TracBrowser for help on using the repository browser.