3ac7f47aa18a45155109ab136954dd78eb5c497e
[platform/upstream/python-lxml.git] / doc / html / api / lxml.builder.ElementMaker-class.html
1 <?xml version="1.0" encoding="ascii"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3           "DTD/xhtml1-transitional.dtd">
4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5 <head>
6   <title>lxml.builder.ElementMaker</title>
7   <link rel="stylesheet" href="epydoc.css" type="text/css" />
8   <script type="text/javascript" src="epydoc.js"></script>
9 </head>
10
11 <body bgcolor="white" text="black" link="blue" vlink="#204080"
12       alink="#204080">
13 <!-- ==================== NAVIGATION BAR ==================== -->
14 <table class="navbar" border="0" width="100%" cellpadding="0"
15        bgcolor="#a0c0ff" cellspacing="0">
16   <tr valign="middle">
17   <!-- Home link -->
18       <th>&nbsp;&nbsp;&nbsp;<a
19         href="lxml-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
20
21   <!-- Tree link -->
22       <th>&nbsp;&nbsp;&nbsp;<a
23         href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
24
25   <!-- Index link -->
26       <th>&nbsp;&nbsp;&nbsp;<a
27         href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
28
29   <!-- Help link -->
30       <th>&nbsp;&nbsp;&nbsp;<a
31         href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
32
33   <!-- Project homepage -->
34       <th class="navbar" align="right" width="100%">
35         <table border="0" cellpadding="0" cellspacing="0">
36           <tr><th class="navbar" align="center"
37             ><a class="navbar" target="_top" href="/">lxml API</a></th>
38           </tr></table></th>
39   </tr>
40 </table>
41 <table width="100%" cellpadding="0" cellspacing="0">
42   <tr valign="top">
43     <td width="100%">
44       <span class="breadcrumbs">
45         <a href="lxml-module.html">Package&nbsp;lxml</a> ::
46         <a href="lxml.builder-module.html">Module&nbsp;builder</a> ::
47         Class&nbsp;ElementMaker
48       </span>
49     </td>
50     <td>
51       <table cellpadding="0" cellspacing="0">
52         <!-- hide/show private -->
53         <tr><td align="right"><span class="options">[<a href="javascript:void(0);" class="privatelink"
54     onclick="toggle_private();">hide&nbsp;private</a>]</span></td></tr>
55         <tr><td align="right"><span class="options"
56             >[<a href="frames.html" target="_top">frames</a
57             >]&nbsp;|&nbsp;<a href="lxml.builder.ElementMaker-class.html"
58             target="_top">no&nbsp;frames</a>]</span></td></tr>
59       </table>
60     </td>
61   </tr>
62 </table>
63 <!-- ==================== CLASS DESCRIPTION ==================== -->
64 <h1 class="epydoc">Class ElementMaker</h1><p class="nomargin-top"><span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker">source&nbsp;code</a></span></p>
65 <pre class="base-tree">
66 object --+
67          |
68         <strong class="uidshort">ElementMaker</strong>
69 </pre>
70
71 <hr />
72 <p>Element generator factory.</p>
73 <p>Unlike the ordinary Element factory, the E factory allows you to pass in
74 more than just a tag and some optional attributes; you can also pass in
75 text and other elements.  The text is added as either text or tail
76 attributes, and elements are inserted at the right spot.  Some small
77 examples:</p>
78 <pre class="rst-literal-block">
79 &gt;&gt;&gt; from lxml import etree as ET
80 &gt;&gt;&gt; from lxml.builder import E
81
82 &gt;&gt;&gt; ET.tostring(E(&quot;tag&quot;))
83 '&lt;tag/&gt;'
84 &gt;&gt;&gt; ET.tostring(E(&quot;tag&quot;, &quot;text&quot;))
85 '&lt;tag&gt;text&lt;/tag&gt;'
86 &gt;&gt;&gt; ET.tostring(E(&quot;tag&quot;, &quot;text&quot;, key=&quot;value&quot;))
87 '&lt;tag key=&quot;value&quot;&gt;text&lt;/tag&gt;'
88 &gt;&gt;&gt; ET.tostring(E(&quot;tag&quot;, E(&quot;subtag&quot;, &quot;text&quot;), &quot;tail&quot;))
89 '&lt;tag&gt;&lt;subtag&gt;text&lt;/subtag&gt;tail&lt;/tag&gt;'
90 </pre>
91 <p>For simple tags, the factory also allows you to write <tt class="rst-docutils literal"><span class="pre">E.tag(...)</span></tt> instead
92 of <tt class="rst-docutils literal"><span class="pre">E('tag',</span> <span class="pre">...)</span></tt>:</p>
93 <pre class="rst-literal-block">
94 &gt;&gt;&gt; ET.tostring(E.tag())
95 '&lt;tag/&gt;'
96 &gt;&gt;&gt; ET.tostring(E.tag(&quot;text&quot;))
97 '&lt;tag&gt;text&lt;/tag&gt;'
98 &gt;&gt;&gt; ET.tostring(E.tag(E.subtag(&quot;text&quot;), &quot;tail&quot;))
99 '&lt;tag&gt;&lt;subtag&gt;text&lt;/subtag&gt;tail&lt;/tag&gt;'
100 </pre>
101 <p>Here's a somewhat larger example; this shows how to generate HTML
102 documents, using a mix of prepared factory functions for inline elements,
103 nested <tt class="rst-docutils literal">E.tag</tt> calls, and embedded XHTML fragments:</p>
104 <pre class="rst-literal-block">
105 # some common inline elements
106 A = E.a
107 I = E.i
108 B = E.b
109
110 def CLASS(v):
111     # helper function, 'class' is a reserved word
112     return {'class': v}
113
114 page = (
115     E.html(
116         E.head(
117             E.title(&quot;This is a sample document&quot;)
118         ),
119         E.body(
120             E.h1(&quot;Hello!&quot;, CLASS(&quot;title&quot;)),
121             E.p(&quot;This is a paragraph with &quot;, B(&quot;bold&quot;), &quot; text in it!&quot;),
122             E.p(&quot;This is another paragraph, with a &quot;,
123                 A(&quot;link&quot;, href=&quot;http://www.python.org&quot;), &quot;.&quot;),
124             E.p(&quot;Here are some reserved characters: &lt;spam&amp;egg&gt;.&quot;),
125             ET.XML(&quot;&lt;p&gt;And finally, here is an embedded XHTML fragment.&lt;/p&gt;&quot;),
126         )
127     )
128 )
129
130 print ET.tostring(page)
131 </pre>
132 <p>Here's a prettyprinted version of the output from the above script:</p>
133 <pre class="rst-literal-block">
134 &lt;html&gt;
135   &lt;head&gt;
136     &lt;title&gt;This is a sample document&lt;/title&gt;
137   &lt;/head&gt;
138   &lt;body&gt;
139     &lt;h1 class=&quot;title&quot;&gt;Hello!&lt;/h1&gt;
140     &lt;p&gt;This is a paragraph with &lt;b&gt;bold&lt;/b&gt; text in it!&lt;/p&gt;
141     &lt;p&gt;This is another paragraph, with &lt;a href=&quot;http://www.python.org&quot;&gt;link&lt;/a&gt;.&lt;/p&gt;
142     &lt;p&gt;Here are some reserved characters: &amp;lt;spam&amp;amp;egg&amp;gt;.&lt;/p&gt;
143     &lt;p&gt;And finally, here is an embedded XHTML fragment.&lt;/p&gt;
144   &lt;/body&gt;
145 &lt;/html&gt;
146 </pre>
147 <p>For namespace support, you can pass a namespace map (<tt class="rst-docutils literal">nsmap</tt>)
148 and/or a specific target <tt class="rst-docutils literal">namespace</tt> to the ElementMaker class:</p>
149 <pre class="rst-literal-block">
150 &gt;&gt;&gt; E = ElementMaker(namespace=&quot;http://my.ns/&quot;)
151 &gt;&gt;&gt; print(ET.tostring( E.test ))
152 &lt;test xmlns=&quot;http://my.ns/&quot;/&gt;
153
154 &gt;&gt;&gt; E = ElementMaker(namespace=&quot;http://my.ns/&quot;, nsmap={'p':'http://my.ns/'})
155 &gt;&gt;&gt; print(ET.tostring( E.test ))
156 &lt;p:test xmlns:p=&quot;http://my.ns/&quot;/&gt;
157 </pre>
158
159 <!-- ==================== INSTANCE METHODS ==================== -->
160 <a name="section-InstanceMethods"></a>
161 <table class="summary" border="1" cellpadding="3"
162        cellspacing="0" width="100%" bgcolor="white">
163 <tr bgcolor="#70b0f0" class="table-header">
164   <td colspan="2" class="table-header">
165     <table border="0" cellpadding="0" cellspacing="0" width="100%">
166       <tr valign="top">
167         <td align="left"><span class="table-header">Instance Methods</span></td>
168         <td align="right" valign="top"
169          ><span class="options">[<a href="#section-InstanceMethods"
170          class="privatelink" onclick="toggle_private();"
171          >hide private</a>]</span></td>
172       </tr>
173     </table>
174   </td>
175 </tr>
176 <tr>
177     <td width="15%" align="right" valign="top" class="summary">
178       <span class="summary-type">&nbsp;</span>
179     </td><td class="summary">
180       <table width="100%" cellpadding="0" cellspacing="0" border="0">
181         <tr>
182           <td><span class="summary-sig"><a href="lxml.builder.ElementMaker-class.html#__init__" class="summary-sig-name">__init__</a>(<span class="summary-sig-arg">self</span>,
183         <span class="summary-sig-arg">typemap</span>=<span class="summary-sig-default">None</span>,
184         <span class="summary-sig-arg">namespace</span>=<span class="summary-sig-default">None</span>,
185         <span class="summary-sig-arg">nsmap</span>=<span class="summary-sig-default">None</span>,
186         <span class="summary-sig-arg">makeelement</span>=<span class="summary-sig-default">None</span>)</span><br />
187       x.__init__(...) initializes x; see help(type(x)) for signature</td>
188           <td align="right" valign="top">
189             <span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__init__">source&nbsp;code</a></span>
190             
191           </td>
192         </tr>
193       </table>
194       
195     </td>
196   </tr>
197 <tr>
198     <td width="15%" align="right" valign="top" class="summary">
199       <span class="summary-type">&nbsp;</span>
200     </td><td class="summary">
201       <table width="100%" cellpadding="0" cellspacing="0" border="0">
202         <tr>
203           <td><span class="summary-sig"><a name="__call__"></a><span class="summary-sig-name">__call__</span>(<span class="summary-sig-arg">x</span>,
204         <span class="summary-sig-arg">...</span>)</span><br />
205       x(...)</td>
206           <td align="right" valign="top">
207             <span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__call__">source&nbsp;code</a></span>
208             
209           </td>
210         </tr>
211       </table>
212       
213     </td>
214   </tr>
215 <tr>
216     <td width="15%" align="right" valign="top" class="summary">
217       <span class="summary-type">&nbsp;</span>
218     </td><td class="summary">
219       <table width="100%" cellpadding="0" cellspacing="0" border="0">
220         <tr>
221           <td><span class="summary-sig"><a name="__getattr__"></a><span class="summary-sig-name">__getattr__</span>(<span class="summary-sig-arg">self</span>,
222         <span class="summary-sig-arg">tag</span>)</span></td>
223           <td align="right" valign="top">
224             <span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__getattr__">source&nbsp;code</a></span>
225             
226           </td>
227         </tr>
228       </table>
229       
230     </td>
231   </tr>
232 <tr>
233     <td width="15%" align="right" valign="top" class="summary">
234       <span class="summary-type">&nbsp;</span>
235     </td><td class="summary">
236       <table width="100%" cellpadding="0" cellspacing="0" border="0">
237         <tr>
238           <td><span class="summary-sig"><a href="lxml.builder.ElementMaker-class.html#__getattribute__" class="summary-sig-name">__getattribute__</a>(<span class="summary-sig-arg">...</span>)</span><br />
239       x.__getattribute__('name') &lt;==&gt; x.name</td>
240           <td align="right" valign="top">
241             <span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__getattribute__">source&nbsp;code</a></span>
242             
243           </td>
244         </tr>
245       </table>
246       
247     </td>
248   </tr>
249 <tr>
250     <td width="15%" align="right" valign="top" class="summary">
251       <span class="summary-type">a new object with type S, a subtype of T</span>
252     </td><td class="summary">
253       <table width="100%" cellpadding="0" cellspacing="0" border="0">
254         <tr>
255           <td><span class="summary-sig"><a href="lxml.builder.ElementMaker-class.html#__new__" class="summary-sig-name">__new__</a>(<span class="summary-sig-arg">T</span>,
256         <span class="summary-sig-arg">S</span>,
257         <span class="summary-sig-arg">...</span>)</span></td>
258           <td align="right" valign="top">
259             <span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__new__">source&nbsp;code</a></span>
260             
261           </td>
262         </tr>
263       </table>
264       
265     </td>
266   </tr>
267 <tr>
268     <td width="15%" align="right" valign="top" class="summary">
269       <span class="summary-type">&nbsp;</span>
270     </td><td class="summary">
271       <table width="100%" cellpadding="0" cellspacing="0" border="0">
272         <tr>
273           <td><span class="summary-sig"><a href="lxml.builder.ElementMaker-class.html#__reduce__" class="summary-sig-name">__reduce__</a>(<span class="summary-sig-arg">...</span>)</span><br />
274       helper for pickle</td>
275           <td align="right" valign="top">
276             <span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__reduce__">source&nbsp;code</a></span>
277             
278           </td>
279         </tr>
280       </table>
281       
282     </td>
283   </tr>
284 <tr>
285     <td width="15%" align="right" valign="top" class="summary">
286       <span class="summary-type">&nbsp;</span>
287     </td><td class="summary">
288       <table width="100%" cellpadding="0" cellspacing="0" border="0">
289         <tr>
290           <td><span class="summary-sig"><a name="__setstate__"></a><span class="summary-sig-name">__setstate__</span>(<span class="summary-sig-arg">...</span>)</span></td>
291           <td align="right" valign="top">
292             <span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__setstate__">source&nbsp;code</a></span>
293             
294           </td>
295         </tr>
296       </table>
297       
298     </td>
299   </tr>
300   <tr>
301     <td colspan="2" class="summary">
302     <p class="indent-wrapped-lines"><b>Inherited from <code>object</code></b>:
303       <code>__delattr__</code>,
304       <code>__format__</code>,
305       <code>__hash__</code>,
306       <code>__reduce_ex__</code>,
307       <code>__repr__</code>,
308       <code>__setattr__</code>,
309       <code>__sizeof__</code>,
310       <code>__str__</code>,
311       <code>__subclasshook__</code>
312       </p>
313     </td>
314   </tr>
315 </table>
316 <!-- ==================== PROPERTIES ==================== -->
317 <a name="section-Properties"></a>
318 <table class="summary" border="1" cellpadding="3"
319        cellspacing="0" width="100%" bgcolor="white">
320 <tr bgcolor="#70b0f0" class="table-header">
321   <td colspan="2" class="table-header">
322     <table border="0" cellpadding="0" cellspacing="0" width="100%">
323       <tr valign="top">
324         <td align="left"><span class="table-header">Properties</span></td>
325         <td align="right" valign="top"
326          ><span class="options">[<a href="#section-Properties"
327          class="privatelink" onclick="toggle_private();"
328          >hide private</a>]</span></td>
329       </tr>
330     </table>
331   </td>
332 </tr>
333 <tr class="private">
334     <td width="15%" align="right" valign="top" class="summary">
335       <span class="summary-type">&nbsp;</span>
336     </td><td class="summary">
337         <a name="_makeelement"></a><span class="summary-name">_makeelement</span>
338     </td>
339   </tr>
340 <tr class="private">
341     <td width="15%" align="right" valign="top" class="summary">
342       <span class="summary-type">&nbsp;</span>
343     </td><td class="summary">
344         <a name="_namespace"></a><span class="summary-name">_namespace</span>
345     </td>
346   </tr>
347 <tr class="private">
348     <td width="15%" align="right" valign="top" class="summary">
349       <span class="summary-type">&nbsp;</span>
350     </td><td class="summary">
351         <a name="_nsmap"></a><span class="summary-name">_nsmap</span>
352     </td>
353   </tr>
354 <tr class="private">
355     <td width="15%" align="right" valign="top" class="summary">
356       <span class="summary-type">&nbsp;</span>
357     </td><td class="summary">
358         <a name="_typemap"></a><span class="summary-name">_typemap</span>
359     </td>
360   </tr>
361   <tr>
362     <td colspan="2" class="summary">
363     <p class="indent-wrapped-lines"><b>Inherited from <code>object</code></b>:
364       <code>__class__</code>
365       </p>
366     </td>
367   </tr>
368 </table>
369 <!-- ==================== METHOD DETAILS ==================== -->
370 <a name="section-MethodDetails"></a>
371 <table class="details" border="1" cellpadding="3"
372        cellspacing="0" width="100%" bgcolor="white">
373 <tr bgcolor="#70b0f0" class="table-header">
374   <td colspan="2" class="table-header">
375     <table border="0" cellpadding="0" cellspacing="0" width="100%">
376       <tr valign="top">
377         <td align="left"><span class="table-header">Method Details</span></td>
378         <td align="right" valign="top"
379          ><span class="options">[<a href="#section-MethodDetails"
380          class="privatelink" onclick="toggle_private();"
381          >hide private</a>]</span></td>
382       </tr>
383     </table>
384   </td>
385 </tr>
386 </table>
387 <a name="__init__"></a>
388 <div>
389 <table class="details" border="1" cellpadding="3"
390        cellspacing="0" width="100%" bgcolor="white">
391 <tr><td>
392   <table width="100%" cellpadding="0" cellspacing="0" border="0">
393   <tr valign="top"><td>
394   <h3 class="epydoc"><span class="sig"><span class="sig-name">__init__</span>(<span class="sig-arg">self</span>,
395         <span class="sig-arg">typemap</span>=<span class="sig-default">None</span>,
396         <span class="sig-arg">namespace</span>=<span class="sig-default">None</span>,
397         <span class="sig-arg">nsmap</span>=<span class="sig-default">None</span>,
398         <span class="sig-arg">makeelement</span>=<span class="sig-default">None</span>)</span>
399     <br /><em class="fname">(Constructor)</em>
400   </h3>
401   </td><td align="right" valign="top"
402     ><span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__init__">source&nbsp;code</a></span>&nbsp;
403     </td>
404   </tr></table>
405   
406   x.__init__(...) initializes x; see help(type(x)) for signature
407   <dl class="fields">
408     <dt>Overrides:
409         object.__init__
410     </dt>
411   </dl>
412 </td></tr></table>
413 </div>
414 <a name="__getattribute__"></a>
415 <div>
416 <table class="details" border="1" cellpadding="3"
417        cellspacing="0" width="100%" bgcolor="white">
418 <tr><td>
419   <table width="100%" cellpadding="0" cellspacing="0" border="0">
420   <tr valign="top"><td>
421   <h3 class="epydoc"><span class="sig"><span class="sig-name">__getattribute__</span>(<span class="sig-arg">...</span>)</span>
422   </h3>
423   </td><td align="right" valign="top"
424     ><span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__getattribute__">source&nbsp;code</a></span>&nbsp;
425     </td>
426   </tr></table>
427   
428   x.__getattribute__('name') &lt;==&gt; x.name
429   <dl class="fields">
430     <dt>Overrides:
431         object.__getattribute__
432     </dt>
433   </dl>
434 </td></tr></table>
435 </div>
436 <a name="__new__"></a>
437 <div>
438 <table class="details" border="1" cellpadding="3"
439        cellspacing="0" width="100%" bgcolor="white">
440 <tr><td>
441   <table width="100%" cellpadding="0" cellspacing="0" border="0">
442   <tr valign="top"><td>
443   <h3 class="epydoc"><span class="sig"><span class="sig-name">__new__</span>(<span class="sig-arg">T</span>,
444         <span class="sig-arg">S</span>,
445         <span class="sig-arg">...</span>)</span>
446   </h3>
447   </td><td align="right" valign="top"
448     ><span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__new__">source&nbsp;code</a></span>&nbsp;
449     </td>
450   </tr></table>
451   
452   
453   <dl class="fields">
454     <dt>Returns: a new object with type S, a subtype of T</dt>
455     <dt>Overrides:
456         object.__new__
457     </dt>
458   </dl>
459 </td></tr></table>
460 </div>
461 <a name="__reduce__"></a>
462 <div>
463 <table class="details" border="1" cellpadding="3"
464        cellspacing="0" width="100%" bgcolor="white">
465 <tr><td>
466   <table width="100%" cellpadding="0" cellspacing="0" border="0">
467   <tr valign="top"><td>
468   <h3 class="epydoc"><span class="sig"><span class="sig-name">__reduce__</span>(<span class="sig-arg">...</span>)</span>
469   </h3>
470   </td><td align="right" valign="top"
471     ><span class="codelink"><a href="lxml.builder-pysrc.html#ElementMaker.__reduce__">source&nbsp;code</a></span>&nbsp;
472     </td>
473   </tr></table>
474   
475   helper for pickle
476   <dl class="fields">
477     <dt>Overrides:
478         object.__reduce__
479         <dd><em class="note">(inherited documentation)</em></dd>
480     </dt>
481   </dl>
482 </td></tr></table>
483 </div>
484 <br />
485 <!-- ==================== NAVIGATION BAR ==================== -->
486 <table class="navbar" border="0" width="100%" cellpadding="0"
487        bgcolor="#a0c0ff" cellspacing="0">
488   <tr valign="middle">
489   <!-- Home link -->
490       <th>&nbsp;&nbsp;&nbsp;<a
491         href="lxml-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
492
493   <!-- Tree link -->
494       <th>&nbsp;&nbsp;&nbsp;<a
495         href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
496
497   <!-- Index link -->
498       <th>&nbsp;&nbsp;&nbsp;<a
499         href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
500
501   <!-- Help link -->
502       <th>&nbsp;&nbsp;&nbsp;<a
503         href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
504
505   <!-- Project homepage -->
506       <th class="navbar" align="right" width="100%">
507         <table border="0" cellpadding="0" cellspacing="0">
508           <tr><th class="navbar" align="center"
509             ><a class="navbar" target="_top" href="/">lxml API</a></th>
510           </tr></table></th>
511   </tr>
512 </table>
513 <table border="0" cellpadding="0" cellspacing="0" width="100%%">
514   <tr>
515     <td align="left" class="footer">
516     Generated by Epydoc 3.0.1
517     on Wed Jan 29 12:26:21 2020
518     </td>
519     <td align="right" class="footer">
520       <a target="mainFrame" href="http://epydoc.sourceforge.net"
521         >http://epydoc.sourceforge.net</a>
522     </td>
523   </tr>
524 </table>
525
526 <script type="text/javascript">
527   <!--
528   // Private objects are initially displayed (because if
529   // javascript is turned off then we want them to be
530   // visible); but by default, we want to hide them.  So hide
531   // them unless we have a cookie that says to show them.
532   checkCookie();
533   // -->
534 </script>
535 </body>
536 </html>