Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="expaterror-objects.html" /> | |
13 | <link rel="prev" href="module-xml.parsers.expat.html" /> | |
14 | <link rel="parent" href="module-xml.parsers.expat.html" /> | |
15 | <link rel="next" href="expaterror-objects.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>13.5.1 XMLParser Objects </title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="13.5 xml.parsers.expat " | |
25 | href="module-xml.parsers.expat.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="13.5 xml.parsers.expat " | |
28 | href="module-xml.parsers.expat.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="13.5.2 ExpatError Exceptions" | |
31 | href="expaterror-objects.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="module-xml.parsers.expat.html">13.5 xml.parsers.expat </A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="module-xml.parsers.expat.html">13.5 xml.parsers.expat </A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="expaterror-objects.html">13.5.2 ExpatError Exceptions</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H2><A NAME="SECTION0015510000000000000000"></A><A NAME="xmlparser-objects"></A> | |
56 | <BR> | |
57 | 13.5.1 XMLParser Objects | |
58 | </H2> | |
59 | ||
60 | <P> | |
61 | <tt class="class">xmlparser</tt> objects have the following methods: | |
62 | ||
63 | <P> | |
64 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
65 | <td><nobr><b><tt id='l2h-4308' xml:id='l2h-4308' class="method">Parse</tt></b>(</nobr></td> | |
66 | <td><var>data</var><big>[</big><var>, isfinal</var><big>]</big><var></var>)</td></tr></table></dt> | |
67 | <dd> | |
68 | Parses the contents of the string <var>data</var>, calling the appropriate | |
69 | handler functions to process the parsed data. <var>isfinal</var> must be | |
70 | true on the final call to this method. <var>data</var> can be the empty | |
71 | string at any time. | |
72 | </dl> | |
73 | ||
74 | <P> | |
75 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
76 | <td><nobr><b><tt id='l2h-4309' xml:id='l2h-4309' class="method">ParseFile</tt></b>(</nobr></td> | |
77 | <td><var>file</var>)</td></tr></table></dt> | |
78 | <dd> | |
79 | Parse XML data reading from the object <var>file</var>. <var>file</var> only | |
80 | needs to provide the <tt class="method">read(<var>nbytes</var>)</tt> method, returning the | |
81 | empty string when there's no more data. | |
82 | </dl> | |
83 | ||
84 | <P> | |
85 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
86 | <td><nobr><b><tt id='l2h-4310' xml:id='l2h-4310' class="method">SetBase</tt></b>(</nobr></td> | |
87 | <td><var>base</var>)</td></tr></table></dt> | |
88 | <dd> | |
89 | Sets the base to be used for resolving relative URIs in system | |
90 | identifiers in declarations. Resolving relative identifiers is left | |
91 | to the application: this value will be passed through as the | |
92 | <var>base</var> argument to the <tt class="function">ExternalEntityRefHandler</tt>, | |
93 | <tt class="function">NotationDeclHandler</tt>, and | |
94 | <tt class="function">UnparsedEntityDeclHandler</tt> functions. | |
95 | </dl> | |
96 | ||
97 | <P> | |
98 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
99 | <td><nobr><b><tt id='l2h-4311' xml:id='l2h-4311' class="method">GetBase</tt></b>(</nobr></td> | |
100 | <td><var></var>)</td></tr></table></dt> | |
101 | <dd> | |
102 | Returns a string containing the base set by a previous call to | |
103 | <tt class="method">SetBase()</tt>, or <code>None</code> if | |
104 | <tt class="method">SetBase()</tt> hasn't been called. | |
105 | </dl> | |
106 | ||
107 | <P> | |
108 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
109 | <td><nobr><b><tt id='l2h-4312' xml:id='l2h-4312' class="method">GetInputContext</tt></b>(</nobr></td> | |
110 | <td><var></var>)</td></tr></table></dt> | |
111 | <dd> | |
112 | Returns the input data that generated the current event as a string. | |
113 | The data is in the encoding of the entity which contains the text. | |
114 | When called while an event handler is not active, the return value is | |
115 | <code>None</code>. | |
116 | ||
117 | <span class="versionnote">New in version 2.1.</span> | |
118 | ||
119 | </dl> | |
120 | ||
121 | <P> | |
122 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
123 | <td><nobr><b><tt id='l2h-4313' xml:id='l2h-4313' class="method">ExternalEntityParserCreate</tt></b>(</nobr></td> | |
124 | <td><var>context</var><big>[</big><var>, | |
125 | encoding</var><big>]</big><var></var>)</td></tr></table></dt> | |
126 | <dd> | |
127 | Create a ``child'' parser which can be used to parse an external | |
128 | parsed entity referred to by content parsed by the parent parser. The | |
129 | <var>context</var> parameter should be the string passed to the | |
130 | <tt class="method">ExternalEntityRefHandler()</tt> handler function, described below. | |
131 | The child parser is created with the <tt class="member">ordered_attributes</tt>, | |
132 | <tt class="member">returns_unicode</tt> and <tt class="member">specified_attributes</tt> set to the | |
133 | values of this parser. | |
134 | </dl> | |
135 | ||
136 | <P> | |
137 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
138 | <td><nobr><b><tt id='l2h-4314' xml:id='l2h-4314' class="method">UseForeignDTD</tt></b>(</nobr></td> | |
139 | <td><var></var><big>[</big><var>flag</var><big>]</big><var></var>)</td></tr></table></dt> | |
140 | <dd> | |
141 | Calling this with a true value for <var>flag</var> (the default) will cause | |
142 | Expat to call the <tt class="member">ExternalEntityRefHandler</tt> with | |
143 | <tt class="constant">None</tt> for all arguments to allow an alternate DTD to be | |
144 | loaded. If the document does not contain a document type declaration, | |
145 | the <tt class="member">ExternalEntityRefHandler</tt> will still be called, but the | |
146 | <tt class="member">StartDoctypeDeclHandler</tt> and <tt class="member">EndDoctypeDeclHandler</tt> | |
147 | will not be called. | |
148 | ||
149 | <P> | |
150 | Passing a false value for <var>flag</var> will cancel a previous call that | |
151 | passed a true value, but otherwise has no effect. | |
152 | ||
153 | <P> | |
154 | This method can only be called before the <tt class="method">Parse()</tt> or | |
155 | <tt class="method">ParseFile()</tt> methods are called; calling it after either of | |
156 | those have been called causes <tt class="exception">ExpatError</tt> to be raised with | |
157 | the <tt class="member">code</tt> attribute set to | |
158 | <tt class="constant">errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</tt>. | |
159 | ||
160 | <P> | |
161 | ||
162 | <span class="versionnote">New in version 2.3.</span> | |
163 | ||
164 | </dl> | |
165 | ||
166 | <P> | |
167 | <tt class="class">xmlparser</tt> objects have the following attributes: | |
168 | ||
169 | <P> | |
170 | <dl><dt><b><tt id='l2h-4315' xml:id='l2h-4315' class="member">buffer_size</tt></b></dt> | |
171 | <dd> | |
172 | The size of the buffer used when <tt class="member">buffer_text</tt> is true. This | |
173 | value cannot be changed at this time. | |
174 | ||
175 | <span class="versionnote">New in version 2.3.</span> | |
176 | ||
177 | </dl> | |
178 | ||
179 | <P> | |
180 | <dl><dt><b><tt id='l2h-4316' xml:id='l2h-4316' class="member">buffer_text</tt></b></dt> | |
181 | <dd> | |
182 | Setting this to true causes the <tt class="class">xmlparser</tt> object to buffer | |
183 | textual content returned by Expat to avoid multiple calls to the | |
184 | <tt class="method">CharacterDataHandler()</tt> callback whenever possible. This can | |
185 | improve performance substantially since Expat normally breaks | |
186 | character data into chunks at every line ending. This attribute is | |
187 | false by default, and may be changed at any time. | |
188 | ||
189 | <span class="versionnote">New in version 2.3.</span> | |
190 | ||
191 | </dl> | |
192 | ||
193 | <P> | |
194 | <dl><dt><b><tt id='l2h-4317' xml:id='l2h-4317' class="member">buffer_used</tt></b></dt> | |
195 | <dd> | |
196 | If <tt class="member">buffer_text</tt> is enabled, the number of bytes stored in the | |
197 | buffer. These bytes represent UTF-8 encoded text. This attribute has | |
198 | no meaningful interpretation when <tt class="member">buffer_text</tt> is false. | |
199 | ||
200 | <span class="versionnote">New in version 2.3.</span> | |
201 | ||
202 | </dl> | |
203 | ||
204 | <P> | |
205 | <dl><dt><b><tt id='l2h-4318' xml:id='l2h-4318' class="member">ordered_attributes</tt></b></dt> | |
206 | <dd> | |
207 | Setting this attribute to a non-zero integer causes the attributes to | |
208 | be reported as a list rather than a dictionary. The attributes are | |
209 | presented in the order found in the document text. For each | |
210 | attribute, two list entries are presented: the attribute name and the | |
211 | attribute value. (Older versions of this module also used this | |
212 | format.) By default, this attribute is false; it may be changed at | |
213 | any time. | |
214 | ||
215 | <span class="versionnote">New in version 2.1.</span> | |
216 | ||
217 | </dl> | |
218 | ||
219 | <P> | |
220 | <dl><dt><b><tt id='l2h-4319' xml:id='l2h-4319' class="member">returns_unicode</tt></b></dt> | |
221 | <dd> | |
222 | If this attribute is set to a non-zero integer, the handler functions | |
223 | will be passed Unicode strings. If <tt class="member">returns_unicode</tt> is 0, | |
224 | 8-bit strings containing UTF-8 encoded data will be passed to the | |
225 | handlers. | |
226 | ||
227 | <span class="versionnote">Changed in version 1.6: | |
228 | Can be changed at any time to affect the result | |
229 | type.</span> | |
230 | ||
231 | </dl> | |
232 | ||
233 | <P> | |
234 | <dl><dt><b><tt id='l2h-4320' xml:id='l2h-4320' class="member">specified_attributes</tt></b></dt> | |
235 | <dd> | |
236 | If set to a non-zero integer, the parser will report only those | |
237 | attributes which were specified in the document instance and not those | |
238 | which were derived from attribute declarations. Applications which | |
239 | set this need to be especially careful to use what additional | |
240 | information is available from the declarations as needed to comply | |
241 | with the standards for the behavior of XML processors. By default, | |
242 | this attribute is false; it may be changed at any time. | |
243 | ||
244 | <span class="versionnote">New in version 2.1.</span> | |
245 | ||
246 | </dl> | |
247 | ||
248 | <P> | |
249 | The following attributes contain values relating to the most recent | |
250 | error encountered by an <tt class="class">xmlparser</tt> object, and will only have | |
251 | correct values once a call to <tt class="method">Parse()</tt> or <tt class="method">ParseFile()</tt> | |
252 | has raised a <tt class="exception">xml.parsers.expat.ExpatError</tt> exception. | |
253 | ||
254 | <P> | |
255 | <dl><dt><b><tt id='l2h-4321' xml:id='l2h-4321' class="member">ErrorByteIndex</tt></b></dt> | |
256 | <dd> | |
257 | Byte index at which an error occurred. | |
258 | </dl> | |
259 | ||
260 | <P> | |
261 | <dl><dt><b><tt id='l2h-4322' xml:id='l2h-4322' class="member">ErrorCode</tt></b></dt> | |
262 | <dd> | |
263 | Numeric code specifying the problem. This value can be passed to the | |
264 | <tt class="function">ErrorString()</tt> function, or compared to one of the constants | |
265 | defined in the <code>errors</code> object. | |
266 | </dl> | |
267 | ||
268 | <P> | |
269 | <dl><dt><b><tt id='l2h-4323' xml:id='l2h-4323' class="member">ErrorColumnNumber</tt></b></dt> | |
270 | <dd> | |
271 | Column number at which an error occurred. | |
272 | </dl> | |
273 | ||
274 | <P> | |
275 | <dl><dt><b><tt id='l2h-4324' xml:id='l2h-4324' class="member">ErrorLineNumber</tt></b></dt> | |
276 | <dd> | |
277 | Line number at which an error occurred. | |
278 | </dl> | |
279 | ||
280 | <P> | |
281 | The following attributes contain values relating to the current parse | |
282 | location in an <tt class="class">xmlparser</tt> object. During a callback reporting | |
283 | a parse event they indicate the location of the first of the sequence | |
284 | of characters that generated the event. When called outside of a | |
285 | callback, the position indicated will be just past the last parse | |
286 | event (regardless of whether there was an associated callback). | |
287 | ||
288 | <span class="versionnote">New in version 2.4.</span> | |
289 | ||
290 | <P> | |
291 | <dl><dt><b><tt id='l2h-4325' xml:id='l2h-4325' class="member">CurrentByteIndex</tt></b></dt> | |
292 | <dd> | |
293 | Current byte index in the parser input. | |
294 | </dl> | |
295 | ||
296 | <P> | |
297 | <dl><dt><b><tt id='l2h-4326' xml:id='l2h-4326' class="member">CurrentColumnNumber</tt></b></dt> | |
298 | <dd> | |
299 | Current column number in the parser input. | |
300 | </dl> | |
301 | ||
302 | <P> | |
303 | <dl><dt><b><tt id='l2h-4327' xml:id='l2h-4327' class="member">CurrentLineNumber</tt></b></dt> | |
304 | <dd> | |
305 | Current line number in the parser input. | |
306 | </dl> | |
307 | ||
308 | <P> | |
309 | Here is the list of handlers that can be set. To set a handler on an | |
310 | <tt class="class">xmlparser</tt> object <var>o</var>, use | |
311 | <code><var>o</var>.<var>handlername</var> = <var>func</var></code>. <var>handlername</var> must | |
312 | be taken from the following list, and <var>func</var> must be a callable | |
313 | object accepting the correct number of arguments. The arguments are | |
314 | all strings, unless otherwise stated. | |
315 | ||
316 | <P> | |
317 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
318 | <td><nobr><b><tt id='l2h-4328' xml:id='l2h-4328' class="method">XmlDeclHandler</tt></b>(</nobr></td> | |
319 | <td><var>version, encoding, standalone</var>)</td></tr></table></dt> | |
320 | <dd> | |
321 | Called when the XML declaration is parsed. The XML declaration is the | |
322 | (optional) declaration of the applicable version of the XML | |
323 | recommendation, the encoding of the document text, and an optional | |
324 | ``standalone'' declaration. <var>version</var> and <var>encoding</var> will be | |
325 | strings of the type dictated by the <tt class="member">returns_unicode</tt> | |
326 | attribute, and <var>standalone</var> will be <code>1</code> if the document is | |
327 | declared standalone, <code>0</code> if it is declared not to be standalone, | |
328 | or <code>-1</code> if the standalone clause was omitted. | |
329 | This is only available with Expat version 1.95.0 or newer. | |
330 | ||
331 | <span class="versionnote">New in version 2.1.</span> | |
332 | ||
333 | </dl> | |
334 | ||
335 | <P> | |
336 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
337 | <td><nobr><b><tt id='l2h-4329' xml:id='l2h-4329' class="method">StartDoctypeDeclHandler</tt></b>(</nobr></td> | |
338 | <td><var>doctypeName, | |
339 | systemId, publicId, | |
340 | has_internal_subset</var>)</td></tr></table></dt> | |
341 | <dd> | |
342 | Called when Expat begins parsing the document type declaration | |
343 | (<code><!DOCTYPE ...</code>). The <var>doctypeName</var> is provided exactly | |
344 | as presented. The <var>systemId</var> and <var>publicId</var> parameters give | |
345 | the system and public identifiers if specified, or <code>None</code> if | |
346 | omitted. <var>has_internal_subset</var> will be true if the document | |
347 | contains and internal document declaration subset. | |
348 | This requires Expat version 1.2 or newer. | |
349 | </dl> | |
350 | ||
351 | <P> | |
352 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
353 | <td><nobr><b><tt id='l2h-4330' xml:id='l2h-4330' class="method">EndDoctypeDeclHandler</tt></b>(</nobr></td> | |
354 | <td><var></var>)</td></tr></table></dt> | |
355 | <dd> | |
356 | Called when Expat is done parsing the document type declaration. | |
357 | This requires Expat version 1.2 or newer. | |
358 | </dl> | |
359 | ||
360 | <P> | |
361 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
362 | <td><nobr><b><tt id='l2h-4331' xml:id='l2h-4331' class="method">ElementDeclHandler</tt></b>(</nobr></td> | |
363 | <td><var>name, model</var>)</td></tr></table></dt> | |
364 | <dd> | |
365 | Called once for each element type declaration. <var>name</var> is the name | |
366 | of the element type, and <var>model</var> is a representation of the | |
367 | content model. | |
368 | </dl> | |
369 | ||
370 | <P> | |
371 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
372 | <td><nobr><b><tt id='l2h-4332' xml:id='l2h-4332' class="method">AttlistDeclHandler</tt></b>(</nobr></td> | |
373 | <td><var>elname, attname, | |
374 | type, default, required</var>)</td></tr></table></dt> | |
375 | <dd> | |
376 | Called for each declared attribute for an element type. If an | |
377 | attribute list declaration declares three attributes, this handler is | |
378 | called three times, once for each attribute. <var>elname</var> is the name | |
379 | of the element to which the declaration applies and <var>attname</var> is | |
380 | the name of the attribute declared. The attribute type is a string | |
381 | passed as <var>type</var>; the possible values are <code>'CDATA'</code>, | |
382 | <code>'ID'</code>, <code>'IDREF'</code>, ... | |
383 | <var>default</var> gives the default value for the attribute used when the | |
384 | attribute is not specified by the document instance, or <code>None</code> if | |
385 | there is no default value (<code>#IMPLIED</code> values). If the attribute | |
386 | is required to be given in the document instance, <var>required</var> will | |
387 | be true. | |
388 | This requires Expat version 1.95.0 or newer. | |
389 | </dl> | |
390 | ||
391 | <P> | |
392 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
393 | <td><nobr><b><tt id='l2h-4333' xml:id='l2h-4333' class="method">StartElementHandler</tt></b>(</nobr></td> | |
394 | <td><var>name, attributes</var>)</td></tr></table></dt> | |
395 | <dd> | |
396 | Called for the start of every element. <var>name</var> is a string | |
397 | containing the element name, and <var>attributes</var> is a dictionary | |
398 | mapping attribute names to their values. | |
399 | </dl> | |
400 | ||
401 | <P> | |
402 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
403 | <td><nobr><b><tt id='l2h-4334' xml:id='l2h-4334' class="method">EndElementHandler</tt></b>(</nobr></td> | |
404 | <td><var>name</var>)</td></tr></table></dt> | |
405 | <dd> | |
406 | Called for the end of every element. | |
407 | </dl> | |
408 | ||
409 | <P> | |
410 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
411 | <td><nobr><b><tt id='l2h-4335' xml:id='l2h-4335' class="method">ProcessingInstructionHandler</tt></b>(</nobr></td> | |
412 | <td><var>target, data</var>)</td></tr></table></dt> | |
413 | <dd> | |
414 | Called for every processing instruction. | |
415 | </dl> | |
416 | ||
417 | <P> | |
418 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
419 | <td><nobr><b><tt id='l2h-4336' xml:id='l2h-4336' class="method">CharacterDataHandler</tt></b>(</nobr></td> | |
420 | <td><var>data</var>)</td></tr></table></dt> | |
421 | <dd> | |
422 | Called for character data. This will be called for normal character | |
423 | data, CDATA marked content, and ignorable whitespace. Applications | |
424 | which must distinguish these cases can use the | |
425 | <tt class="member">StartCdataSectionHandler</tt>, <tt class="member">EndCdataSectionHandler</tt>, | |
426 | and <tt class="member">ElementDeclHandler</tt> callbacks to collect the required | |
427 | information. | |
428 | </dl> | |
429 | ||
430 | <P> | |
431 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
432 | <td><nobr><b><tt id='l2h-4337' xml:id='l2h-4337' class="method">UnparsedEntityDeclHandler</tt></b>(</nobr></td> | |
433 | <td><var>entityName, base, | |
434 | systemId, publicId, | |
435 | notationName</var>)</td></tr></table></dt> | |
436 | <dd> | |
437 | Called for unparsed (NDATA) entity declarations. This is only present | |
438 | for version 1.2 of the Expat library; for more recent versions, use | |
439 | <tt class="member">EntityDeclHandler</tt> instead. (The underlying function in the | |
440 | Expat library has been declared obsolete.) | |
441 | </dl> | |
442 | ||
443 | <P> | |
444 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
445 | <td><nobr><b><tt id='l2h-4338' xml:id='l2h-4338' class="method">EntityDeclHandler</tt></b>(</nobr></td> | |
446 | <td><var>entityName, | |
447 | is_parameter_entity, value, | |
448 | base, systemId, | |
449 | publicId, | |
450 | notationName</var>)</td></tr></table></dt> | |
451 | <dd> | |
452 | Called for all entity declarations. For parameter and internal | |
453 | entities, <var>value</var> will be a string giving the declared contents | |
454 | of the entity; this will be <code>None</code> for external entities. The | |
455 | <var>notationName</var> parameter will be <code>None</code> for parsed entities, | |
456 | and the name of the notation for unparsed entities. | |
457 | <var>is_parameter_entity</var> will be true if the entity is a parameter | |
458 | entity or false for general entities (most applications only need to | |
459 | be concerned with general entities). | |
460 | This is only available starting with version 1.95.0 of the Expat | |
461 | library. | |
462 | ||
463 | <span class="versionnote">New in version 2.1.</span> | |
464 | ||
465 | </dl> | |
466 | ||
467 | <P> | |
468 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
469 | <td><nobr><b><tt id='l2h-4339' xml:id='l2h-4339' class="method">NotationDeclHandler</tt></b>(</nobr></td> | |
470 | <td><var>notationName, base, | |
471 | systemId, publicId</var>)</td></tr></table></dt> | |
472 | <dd> | |
473 | Called for notation declarations. <var>notationName</var>, <var>base</var>, and | |
474 | <var>systemId</var>, and <var>publicId</var> are strings if given. If the | |
475 | public identifier is omitted, <var>publicId</var> will be <code>None</code>. | |
476 | </dl> | |
477 | ||
478 | <P> | |
479 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
480 | <td><nobr><b><tt id='l2h-4340' xml:id='l2h-4340' class="method">StartNamespaceDeclHandler</tt></b>(</nobr></td> | |
481 | <td><var>prefix, uri</var>)</td></tr></table></dt> | |
482 | <dd> | |
483 | Called when an element contains a namespace declaration. Namespace | |
484 | declarations are processed before the <tt class="member">StartElementHandler</tt> is | |
485 | called for the element on which declarations are placed. | |
486 | </dl> | |
487 | ||
488 | <P> | |
489 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
490 | <td><nobr><b><tt id='l2h-4341' xml:id='l2h-4341' class="method">EndNamespaceDeclHandler</tt></b>(</nobr></td> | |
491 | <td><var>prefix</var>)</td></tr></table></dt> | |
492 | <dd> | |
493 | Called when the closing tag is reached for an element | |
494 | that contained a namespace declaration. This is called once for each | |
495 | namespace declaration on the element in the reverse of the order for | |
496 | which the <tt class="member">StartNamespaceDeclHandler</tt> was called to indicate | |
497 | the start of each namespace declaration's scope. Calls to this | |
498 | handler are made after the corresponding <tt class="member">EndElementHandler</tt> | |
499 | for the end of the element. | |
500 | </dl> | |
501 | ||
502 | <P> | |
503 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
504 | <td><nobr><b><tt id='l2h-4342' xml:id='l2h-4342' class="method">CommentHandler</tt></b>(</nobr></td> | |
505 | <td><var>data</var>)</td></tr></table></dt> | |
506 | <dd> | |
507 | Called for comments. <var>data</var> is the text of the comment, excluding | |
508 | the leading `<code><!-</code><code>-</code>' and trailing `<code>-</code><code>-></code>'. | |
509 | </dl> | |
510 | ||
511 | <P> | |
512 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
513 | <td><nobr><b><tt id='l2h-4343' xml:id='l2h-4343' class="method">StartCdataSectionHandler</tt></b>(</nobr></td> | |
514 | <td><var></var>)</td></tr></table></dt> | |
515 | <dd> | |
516 | Called at the start of a CDATA section. This and | |
517 | <tt class="member">StartCdataSectionHandler</tt> are needed to be able to identify | |
518 | the syntactical start and end for CDATA sections. | |
519 | </dl> | |
520 | ||
521 | <P> | |
522 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
523 | <td><nobr><b><tt id='l2h-4344' xml:id='l2h-4344' class="method">EndCdataSectionHandler</tt></b>(</nobr></td> | |
524 | <td><var></var>)</td></tr></table></dt> | |
525 | <dd> | |
526 | Called at the end of a CDATA section. | |
527 | </dl> | |
528 | ||
529 | <P> | |
530 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
531 | <td><nobr><b><tt id='l2h-4345' xml:id='l2h-4345' class="method">DefaultHandler</tt></b>(</nobr></td> | |
532 | <td><var>data</var>)</td></tr></table></dt> | |
533 | <dd> | |
534 | Called for any characters in the XML document for | |
535 | which no applicable handler has been specified. This means | |
536 | characters that are part of a construct which could be reported, but | |
537 | for which no handler has been supplied. | |
538 | </dl> | |
539 | ||
540 | <P> | |
541 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
542 | <td><nobr><b><tt id='l2h-4346' xml:id='l2h-4346' class="method">DefaultHandlerExpand</tt></b>(</nobr></td> | |
543 | <td><var>data</var>)</td></tr></table></dt> | |
544 | <dd> | |
545 | This is the same as the <tt class="function">DefaultHandler</tt>, | |
546 | but doesn't inhibit expansion of internal entities. | |
547 | The entity reference will not be passed to the default handler. | |
548 | </dl> | |
549 | ||
550 | <P> | |
551 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
552 | <td><nobr><b><tt id='l2h-4347' xml:id='l2h-4347' class="method">NotStandaloneHandler</tt></b>(</nobr></td> | |
553 | <td><var></var>)</td></tr></table></dt> | |
554 | <dd> Called if the | |
555 | XML document hasn't been declared as being a standalone document. | |
556 | This happens when there is an external subset or a reference to a | |
557 | parameter entity, but the XML declaration does not set standalone to | |
558 | <code>yes</code> in an XML declaration. If this handler returns <code>0</code>, | |
559 | then the parser will throw an <tt class="constant">XML_ERROR_NOT_STANDALONE</tt> | |
560 | error. If this handler is not set, no exception is raised by the | |
561 | parser for this condition. | |
562 | </dl> | |
563 | ||
564 | <P> | |
565 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
566 | <td><nobr><b><tt id='l2h-4348' xml:id='l2h-4348' class="method">ExternalEntityRefHandler</tt></b>(</nobr></td> | |
567 | <td><var>context, base, | |
568 | systemId, publicId</var>)</td></tr></table></dt> | |
569 | <dd> | |
570 | Called for references to external entities. <var>base</var> is the current | |
571 | base, as set by a previous call to <tt class="method">SetBase()</tt>. The public and | |
572 | system identifiers, <var>systemId</var> and <var>publicId</var>, are strings if | |
573 | given; if the public identifier is not given, <var>publicId</var> will be | |
574 | <code>None</code>. The <var>context</var> value is opaque and should only be | |
575 | used as described below. | |
576 | ||
577 | <P> | |
578 | For external entities to be parsed, this handler must be implemented. | |
579 | It is responsible for creating the sub-parser using | |
580 | <code>ExternalEntityParserCreate(<var>context</var>)</code>, initializing it with | |
581 | the appropriate callbacks, and parsing the entity. This handler | |
582 | should return an integer; if it returns <code>0</code>, the parser will | |
583 | throw an <tt class="constant">XML_ERROR_EXTERNAL_ENTITY_HANDLING</tt> error, | |
584 | otherwise parsing will continue. | |
585 | ||
586 | <P> | |
587 | If this handler is not provided, external entities are reported by the | |
588 | <tt class="member">DefaultHandler</tt> callback, if provided. | |
589 | </dl> | |
590 | ||
591 | <P> | |
592 | ||
593 | <DIV CLASS="navigation"> | |
594 | <div class='online-navigation'> | |
595 | <p></p><hr /> | |
596 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
597 | <tr> | |
598 | <td class='online-navigation'><a rel="prev" title="13.5 xml.parsers.expat " | |
599 | href="module-xml.parsers.expat.html"><img src='../icons/previous.png' | |
600 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
601 | <td class='online-navigation'><a rel="parent" title="13.5 xml.parsers.expat " | |
602 | href="module-xml.parsers.expat.html"><img src='../icons/up.png' | |
603 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
604 | <td class='online-navigation'><a rel="next" title="13.5.2 ExpatError Exceptions" | |
605 | href="expaterror-objects.html"><img src='../icons/next.png' | |
606 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
607 | <td align="center" width="100%">Python Library Reference</td> | |
608 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
609 | href="contents.html"><img src='../icons/contents.png' | |
610 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
611 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
612 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
613 | <td class='online-navigation'><a rel="index" title="Index" | |
614 | href="genindex.html"><img src='../icons/index.png' | |
615 | border='0' height='32' alt='Index' width='32' /></A></td> | |
616 | </tr></table> | |
617 | <div class='online-navigation'> | |
618 | <b class="navlabel">Previous:</b> | |
619 | <a class="sectref" rel="prev" href="module-xml.parsers.expat.html">13.5 xml.parsers.expat </A> | |
620 | <b class="navlabel">Up:</b> | |
621 | <a class="sectref" rel="parent" href="module-xml.parsers.expat.html">13.5 xml.parsers.expat </A> | |
622 | <b class="navlabel">Next:</b> | |
623 | <a class="sectref" rel="next" href="expaterror-objects.html">13.5.2 ExpatError Exceptions</A> | |
624 | </div> | |
625 | </div> | |
626 | <hr /> | |
627 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
628 | </DIV> | |
629 | <!--End of Navigation Panel--> | |
630 | <ADDRESS> | |
631 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
632 | </ADDRESS> | |
633 | </BODY> | |
634 | </HTML> |