Debian Codegraph @

Doc/library/pyexpat.rst

raw
1 :mod:`!xml.parsers.expat` --- Fast XML parsing using Expat
2 ==========================================================
3
4 .. module:: xml.parsers.expat
5 :synopsis: An interface to the Expat non-validating XML parser.
6
7 .. moduleauthor:: Paul Prescod <[email protected]>
8
9 --------------
10
11 .. Markup notes:
12
13 Many of the attributes of the XMLParser objects are callbacks. Since
14 signature information must be presented, these are described using the method
15 directive. Since they are attributes which are set by client code, in-text
16 references to these attributes should be marked using the :member: role.
17
18
19 .. note::
20
21 If you need to parse untrusted or unauthenticated data, see
22 :ref:`xml-security`.
23
24
25 .. index:: single: Expat
26
27 The :mod:`!xml.parsers.expat` module is a Python interface to the Expat
28 non-validating XML parser. The module provides a single extension type,
29 :class:`xmlparser`, that represents the current state of an XML parser. After
30 an :class:`xmlparser` object has been created, various attributes of the object
31 can be set to handler functions. When an XML document is then fed to the
32 parser, the handler functions are called for the character data and markup in
33 the XML document.
34
35 .. index:: pair: module; pyexpat
36
37 This module uses the :mod:`pyexpat` module to provide access to the Expat
38 parser. Direct use of the :mod:`pyexpat` module is deprecated.
39
40 This module provides one exception and one type object:
41
42
43 .. exception:: ExpatError
44
45 The exception raised when Expat reports an error. See section
46 :ref:`expaterror-objects` for more information on interpreting Expat errors.
47
48
49 .. exception:: error
50
51 Alias for :exc:`ExpatError`.
52
53
54 .. data:: XMLParserType
55
56 The type of the return values from the :func:`ParserCreate` function.
57
58 The :mod:`!xml.parsers.expat` module contains two functions:
59
60
61 .. function:: ErrorString(errno)
62
63 Returns an explanatory string for a given error number *errno*.
64
65
66 .. function:: ParserCreate(encoding=None, namespace_separator=None)
67
68 Creates and returns a new :class:`xmlparser` object. *encoding*, if specified,
69 must be a string naming the encoding used by the XML data. Expat doesn't
70 support as many encodings as Python does, and its repertoire of encodings can't
71 be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If
72 *encoding* [1]_ is given it will override the implicit or explicit encoding of the
73 document.
74
75 .. _xmlparser-non-root:
76
77 Parsers created through :func:`!ParserCreate` are called "root" parsers,
78 in the sense that they do not have any parent parser attached. Non-root
79 parsers are created by :meth:`parser.ExternalEntityParserCreate
80 <xmlparser.ExternalEntityParserCreate>`.
81
82 Expat can optionally do XML namespace processing for you, enabled by providing a
83 value for *namespace_separator*. The value must be a one-character string; a
84 :exc:`ValueError` will be raised if the string has an illegal length (``None``
85 is considered the same as omission). When namespace processing is enabled,
86 element type names and attribute names that belong to a namespace will be
87 expanded. The element name passed to the element handlers
88 :attr:`StartElementHandler` and :attr:`EndElementHandler` will be the
89 concatenation of the namespace URI, the namespace separator character, and the
90 local part of the name. If the namespace separator is a zero byte (``chr(0)``)
91 then the namespace URI and the local part will be concatenated without any
92 separator.
93
94 For example, if *namespace_separator* is set to a space character (``' '``) and
95 the following document is parsed:
96
97 .. code-block:: xml
98
99 <?xml version="1.0"?>
100 <root xmlns = "http://default-namespace.org/"
101 xmlns:py = "http://www.python.org/ns/">
102 <py:elem1 />
103 <elem2 xmlns="" />
104 </root>
105
106 :attr:`StartElementHandler` will receive the following strings for each
107 element::
108
109 http://default-namespace.org/ root
110 http://www.python.org/ns/ elem1
111 elem2
112
113 Due to limitations in the ``Expat`` library used by :mod:`pyexpat`,
114 the :class:`xmlparser` instance returned can only be used to parse a single
115 XML document. Call ``ParserCreate`` for each document to provide unique
116 parser instances.
117
118
119 .. seealso::
120
121 `The Expat XML Parser <http://www.libexpat.org/>`_
122 Home page of the Expat project.
123
124
125 .. _xmlparser-objects:
126
127 XMLParser Objects
128 -----------------
129
130 :class:`xmlparser` objects have the following methods:
131
132
133 .. method:: xmlparser.Parse(data[, isfinal])
134
135 Parses the contents of the string *data*, calling the appropriate handler
136 functions to process the parsed data. *isfinal* must be true on the final call
137 to this method; it allows the parsing of a single file in fragments,
138 not the submission of multiple files.
139 *data* can be the empty string at any time.
140
141
142 .. method:: xmlparser.ParseFile(file)
143
144 Parse XML data reading from the object *file*. *file* only needs to provide
145 the ``read(nbytes)`` method, returning the empty string when there's no more
146 data.
147
148
149 .. method:: xmlparser.SetBase(base)
150
151 Sets the base to be used for resolving relative URIs in system identifiers in
152 declarations. Resolving relative identifiers is left to the application: this
153 value will be passed through as the *base* argument to the
154 :func:`ExternalEntityRefHandler`, :func:`NotationDeclHandler`, and
155 :func:`UnparsedEntityDeclHandler` functions.
156
157
158 .. method:: xmlparser.GetBase()
159
160 Returns a string containing the base set by a previous call to :meth:`SetBase`,
161 or ``None`` if :meth:`SetBase` hasn't been called.
162
163
164 .. method:: xmlparser.GetInputContext()
165
166 Returns the input data that generated the current event as a string. The data is
167 in the encoding of the entity which contains the text. When called while an
168 event handler is not active, the return value is ``None``.
169
170
171 .. method:: xmlparser.ExternalEntityParserCreate(context[, encoding])
172
173 Create a "child" parser which can be used to parse an external parsed entity
174 referred to by content parsed by the parent parser. The *context* parameter
175 should be the string passed to the :meth:`ExternalEntityRefHandler` handler
176 function, described below. The child parser is created with the
177 :attr:`ordered_attributes` and :attr:`specified_attributes` set to the values of
178 this parser.
179
180 .. method:: xmlparser.SetParamEntityParsing(flag)
181
182 Control parsing of parameter entities (including the external DTD subset).
183 Possible *flag* values are :const:`XML_PARAM_ENTITY_PARSING_NEVER`,
184 :const:`XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE` and
185 :const:`XML_PARAM_ENTITY_PARSING_ALWAYS`. Return true if setting the flag
186 was successful.
187
188 .. method:: xmlparser.UseForeignDTD([flag])
189
190 Calling this with a true value for *flag* (the default) will cause Expat to call
191 the :attr:`ExternalEntityRefHandler` with :const:`None` for all arguments to
192 allow an alternate DTD to be loaded. If the document does not contain a
193 document type declaration, the :attr:`ExternalEntityRefHandler` will still be
194 called, but the :attr:`StartDoctypeDeclHandler` and
195 :attr:`EndDoctypeDeclHandler` will not be called.
196
197 Passing a false value for *flag* will cancel a previous call that passed a true
198 value, but otherwise has no effect.
199
200 This method can only be called before the :meth:`Parse` or :meth:`ParseFile`
201 methods are called; calling it after either of those have been called causes
202 :exc:`ExpatError` to be raised with the :attr:`code` attribute set to
203 ``errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING]``.
204
205 .. method:: xmlparser.SetReparseDeferralEnabled(enabled)
206
207 .. warning::
208
209 Calling ``SetReparseDeferralEnabled(False)`` has security implications,
210 as detailed below; please make sure to understand these consequences
211 prior to using the ``SetReparseDeferralEnabled`` method.
212
213 Expat 2.6.0 introduced a security mechanism called "reparse deferral"
214 where instead of causing denial of service through quadratic runtime
215 from reparsing large tokens, reparsing of unfinished tokens is now delayed
216 by default until a sufficient amount of input is reached.
217 Due to this delay, registered handlers may — depending of the sizing of
218 input chunks pushed to Expat — no longer be called right after pushing new
219 input to the parser. Where immediate feedback and taking over responsibility
220 of protecting against denial of service from large tokens are both wanted,
221 calling ``SetReparseDeferralEnabled(False)`` disables reparse deferral
222 for the current Expat parser instance, temporarily or altogether.
223 Calling ``SetReparseDeferralEnabled(True)`` allows re-enabling reparse
224 deferral.
225
226 Note that :meth:`SetReparseDeferralEnabled` has been backported to some
227 prior releases of CPython as a security fix. Check for availability of
228 :meth:`SetReparseDeferralEnabled` using :func:`hasattr` if used in code
229 running across a variety of Python versions.
230
231 .. versionadded:: 3.13
232
233 .. method:: xmlparser.GetReparseDeferralEnabled()
234
235 Returns whether reparse deferral is currently enabled for the given
236 Expat parser instance.
237
238 .. versionadded:: 3.13
239
240
241 :class:`!xmlparser` objects have the following methods to tune protections
242 against some common XML vulnerabilities.
243
244 .. method:: xmlparser.SetBillionLaughsAttackProtectionActivationThreshold(threshold, /)
245
246 Sets the number of output bytes needed to activate protection against
247 `billion laughs`_ attacks.
248
249 The number of output bytes includes amplification from entity expansion
250 and reading DTD files.
251
252 Parser objects usually have a protection activation threshold of 8 MiB,
253 but the actual default value depends on the underlying Expat library.
254
255 An :exc:`ExpatError` is raised if this method is called on a
256 |xml-non-root-parser| parser.
257 The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset`
258 should not be used as they may have no special meaning.
259
260 .. note::
261
262 Activation thresholds below 4 MiB are known to break support for DITA 1.3
263 payload and are hence not recommended.
264
265 .. versionadded:: 3.14.6
266
267 .. method:: xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification(max_factor, /)
268
269 Sets the maximum tolerated amplification factor for protection against
270 `billion laughs`_ attacks.
271
272 The amplification factor is calculated as ``(direct + indirect) / direct``
273 while parsing, where ``direct`` is the number of bytes read from
274 the primary document in parsing and ``indirect`` is the number of
275 bytes added by expanding entities and reading of external DTD files.
276
277 The *max_factor* value must be a non-NaN :class:`float` value greater than
278 or equal to 1.0. Peak amplifications of factor 15,000 for the entire payload
279 and of factor 30,000 in the middle of parsing have been observed with small
280 benign files in practice. In particular, the activation threshold should be
281 carefully chosen to avoid false positives.
282
283 Parser objects usually have a maximum amplification factor of 100,
284 but the actual default value depends on the underlying Expat library.
285
286 An :exc:`ExpatError` is raised if this method is called on a
287 |xml-non-root-parser| parser or if *max_factor* is outside the valid range.
288 The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset`
289 should not be used as they may have no special meaning.
290
291 .. note::
292
293 The maximum amplification factor is only considered if the threshold
294 that can be adjusted by :meth:`.SetBillionLaughsAttackProtectionActivationThreshold`
295 is exceeded.
296
297 .. versionadded:: 3.14.6
298
299 .. method:: xmlparser.SetAllocTrackerActivationThreshold(threshold, /)
300
301 Sets the number of allocated bytes of dynamic memory needed to activate
302 protection against disproportionate use of RAM.
303
304 Parser objects usually have an allocation activation threshold of 64 MiB,
305 but the actual default value depends on the underlying Expat library.
306
307 An :exc:`ExpatError` is raised if this method is called on a
308 |xml-non-root-parser| parser.
309 The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset`
310 should not be used as they may have no special meaning.
311
312 .. versionadded:: 3.14.1
313
314 .. method:: xmlparser.SetAllocTrackerMaximumAmplification(max_factor, /)
315
316 Sets the maximum amplification factor between direct input and bytes
317 of dynamic memory allocated.
318
319 The amplification factor is calculated as ``allocated / direct``
320 while parsing, where ``direct`` is the number of bytes read from
321 the primary document in parsing and ``allocated`` is the number
322 of bytes of dynamic memory allocated in the parser hierarchy.
323
324 The *max_factor* value must be a non-NaN :class:`float` value greater than
325 or equal to 1.0. Amplification factors greater than 100.0 can be observed
326 near the start of parsing even with benign files in practice. In particular,
327 the activation threshold should be carefully chosen to avoid false positives.
328
329 Parser objects usually have a maximum amplification factor of 100,
330 but the actual default value depends on the underlying Expat library.
331
332 An :exc:`ExpatError` is raised if this method is called on a
333 |xml-non-root-parser| parser or if *max_factor* is outside the valid range.
334 The corresponding :attr:`~ExpatError.lineno` and :attr:`~ExpatError.offset`
335 should not be used as they may have no special meaning.
336
337 .. note::
338
339 The maximum amplification factor is only considered if the threshold
340 that can be adjusted by :meth:`.SetAllocTrackerActivationThreshold`
341 is exceeded.
342
343 .. versionadded:: 3.14.1
344
345
346 :class:`xmlparser` objects have the following attributes:
347
348
349 .. attribute:: xmlparser.buffer_size
350
351 The size of the buffer used when :attr:`buffer_text` is true.
352 A new buffer size can be set by assigning a new integer value
353 to this attribute.
354 When the size is changed, the buffer will be flushed.
355
356
357 .. attribute:: xmlparser.buffer_text
358
359 Setting this to true causes the :class:`xmlparser` object to buffer textual
360 content returned by Expat to avoid multiple calls to the
361 :meth:`CharacterDataHandler` callback whenever possible. This can improve
362 performance substantially since Expat normally breaks character data into chunks
363 at every line ending. This attribute is false by default, and may be changed at
364 any time. Note that when it is false, data that does not contain newlines
365 may be chunked too.
366
367
368 .. attribute:: xmlparser.buffer_used
369
370 If :attr:`buffer_text` is enabled, the number of bytes stored in the buffer.
371 These bytes represent UTF-8 encoded text. This attribute has no meaningful
372 interpretation when :attr:`buffer_text` is false.
373
374
375 .. attribute:: xmlparser.ordered_attributes
376
377 Setting this attribute to a non-zero integer causes the attributes to be
378 reported as a list rather than a dictionary. The attributes are presented in
379 the order found in the document text. For each attribute, two list entries are
380 presented: the attribute name and the attribute value. (Older versions of this
381 module also used this format.) By default, this attribute is false; it may be
382 changed at any time.
383
384
385 .. attribute:: xmlparser.specified_attributes
386
387 If set to a non-zero integer, the parser will report only those attributes which
388 were specified in the document instance and not those which were derived from
389 attribute declarations. Applications which set this need to be especially
390 careful to use what additional information is available from the declarations as
391 needed to comply with the standards for the behavior of XML processors. By
392 default, this attribute is false; it may be changed at any time.
393
394
395 The following attributes contain values relating to the most recent error
396 encountered by an :class:`xmlparser` object, and will only have correct values
397 once a call to :meth:`Parse` or :meth:`ParseFile` has raised an
398 :exc:`xml.parsers.expat.ExpatError` exception.
399
400
401 .. attribute:: xmlparser.ErrorByteIndex
402
403 Byte index at which an error occurred.
404
405
406 .. attribute:: xmlparser.ErrorCode
407
408 Numeric code specifying the problem. This value can be passed to the
409 :func:`ErrorString` function, or compared to one of the constants defined in the
410 ``errors`` object.
411
412
413 .. attribute:: xmlparser.ErrorColumnNumber
414
415 Column number at which an error occurred.
416
417
418 .. attribute:: xmlparser.ErrorLineNumber
419
420 Line number at which an error occurred.
421
422 The following attributes contain values relating to the current parse location
423 in an :class:`xmlparser` object. During a callback reporting a parse event they
424 indicate the location of the first of the sequence of characters that generated
425 the event. When called outside of a callback, the position indicated will be
426 just past the last parse event (regardless of whether there was an associated
427 callback).
428
429
430 .. attribute:: xmlparser.CurrentByteIndex
431
432 Current byte index in the parser input.
433
434
435 .. attribute:: xmlparser.CurrentColumnNumber
436
437 Current column number in the parser input.
438
439
440 .. attribute:: xmlparser.CurrentLineNumber
441
442 Current line number in the parser input.
443
444 Here is the list of handlers that can be set. To set a handler on an
445 :class:`xmlparser` object *o*, use ``o.handlername = func``. *handlername* must
446 be taken from the following list, and *func* must be a callable object accepting
447 the correct number of arguments. The arguments are all strings, unless
448 otherwise stated.
449
450
451 .. method:: xmlparser.XmlDeclHandler(version, encoding, standalone)
452
453 Called when the XML declaration is parsed. The XML declaration is the
454 (optional) declaration of the applicable version of the XML recommendation, the
455 encoding of the document text, and an optional "standalone" declaration.
456 *version* and *encoding* will be strings, and *standalone* will be ``1`` if the
457 document is declared standalone, ``0`` if it is declared not to be standalone,
458 or ``-1`` if the standalone clause was omitted. This is only available with
459 Expat version 1.95.0 or newer.
460
461
462 .. method:: xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)
463
464 Called when Expat begins parsing the document type declaration (``<!DOCTYPE
465 ...``). The *doctypeName* is provided exactly as presented. The *systemId* and
466 *publicId* parameters give the system and public identifiers if specified, or
467 ``None`` if omitted. *has_internal_subset* will be true if the document
468 contains an internal document declaration subset. This requires Expat version
469 1.2 or newer.
470
471
472 .. method:: xmlparser.EndDoctypeDeclHandler()
473
474 Called when Expat is done parsing the document type declaration. This requires
475 Expat version 1.2 or newer.
476
477
478 .. method:: xmlparser.ElementDeclHandler(name, model)
479
480 Called once for each element type declaration. *name* is the name of the
481 element type, and *model* is a representation of the content model.
482
483
484 .. method:: xmlparser.AttlistDeclHandler(elname, attname, type, default, required)
485
486 Called for each declared attribute for an element type. If an attribute list
487 declaration declares three attributes, this handler is called three times, once
488 for each attribute. *elname* is the name of the element to which the
489 declaration applies and *attname* is the name of the attribute declared. The
490 attribute type is a string passed as *type*; the possible values are
491 ``'CDATA'``, ``'ID'``, ``'IDREF'``, ... *default* gives the default value for
492 the attribute used when the attribute is not specified by the document instance,
493 or ``None`` if there is no default value (``#IMPLIED`` values). If the
494 attribute is required to be given in the document instance, *required* will be
495 true. This requires Expat version 1.95.0 or newer.
496
497
498 .. method:: xmlparser.StartElementHandler(name, attributes)
499
500 Called for the start of every element. *name* is a string containing the
501 element name, and *attributes* is the element attributes. If
502 :attr:`ordered_attributes` is true, this is a list (see
503 :attr:`ordered_attributes` for a full description). Otherwise it's a
504 dictionary mapping names to values.
505
506
507 .. method:: xmlparser.EndElementHandler(name)
508
509 Called for the end of every element.
510
511
512 .. method:: xmlparser.ProcessingInstructionHandler(target, data)
513
514 Called for every processing instruction.
515
516
517 .. method:: xmlparser.CharacterDataHandler(data)
518
519 Called for character data. This will be called for normal character data, CDATA
520 marked content, and ignorable whitespace. Applications which must distinguish
521 these cases can use the :attr:`StartCdataSectionHandler`,
522 :attr:`EndCdataSectionHandler`, and :attr:`ElementDeclHandler` callbacks to
523 collect the required information. Note that the character data may be
524 chunked even if it is short and so you may receive more than one call to
525 :meth:`CharacterDataHandler`. Set the :attr:`buffer_text` instance attribute
526 to ``True`` to avoid that.
527
528
529 .. method:: xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)
530
531 Called for unparsed (NDATA) entity declarations. This is only present for
532 version 1.2 of the Expat library; for more recent versions, use
533 :attr:`EntityDeclHandler` instead. (The underlying function in the Expat
534 library has been declared obsolete.)
535
536
537 .. method:: xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)
538
539 Called for all entity declarations. For parameter and internal entities,
540 *value* will be a string giving the declared contents of the entity; this will
541 be ``None`` for external entities. The *notationName* parameter will be
542 ``None`` for parsed entities, and the name of the notation for unparsed
543 entities. *is_parameter_entity* will be true if the entity is a parameter entity
544 or false for general entities (most applications only need to be concerned with
545 general entities). This is only available starting with version 1.95.0 of the
546 Expat library.
547
548
549 .. method:: xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)
550
551 Called for notation declarations. *notationName*, *base*, and *systemId*, and
552 *publicId* are strings if given. If the public identifier is omitted,
553 *publicId* will be ``None``.
554
555
556 .. method:: xmlparser.StartNamespaceDeclHandler(prefix, uri)
557
558 Called when an element contains a namespace declaration. Namespace declarations
559 are processed before the :attr:`StartElementHandler` is called for the element
560 on which declarations are placed.
561
562
563 .. method:: xmlparser.EndNamespaceDeclHandler(prefix)
564
565 Called when the closing tag is reached for an element that contained a
566 namespace declaration. This is called once for each namespace declaration on
567 the element in the reverse of the order for which the
568 :attr:`StartNamespaceDeclHandler` was called to indicate the start of each
569 namespace declaration's scope. Calls to this handler are made after the
570 corresponding :attr:`EndElementHandler` for the end of the element.
571
572
573 .. method:: xmlparser.CommentHandler(data)
574
575 Called for comments. *data* is the text of the comment, excluding the leading
576 ``'<!-``\ ``-'`` and trailing ``'-``\ ``->'``.
577
578
579 .. method:: xmlparser.StartCdataSectionHandler()
580
581 Called at the start of a CDATA section. This and :attr:`EndCdataSectionHandler`
582 are needed to be able to identify the syntactical start and end for CDATA
583 sections.
584
585
586 .. method:: xmlparser.EndCdataSectionHandler()
587
588 Called at the end of a CDATA section.
589
590
591 .. method:: xmlparser.DefaultHandler(data)
592
593 Called for any characters in the XML document for which no applicable handler
594 has been specified. This means characters that are part of a construct which
595 could be reported, but for which no handler has been supplied.
596
597
598 .. method:: xmlparser.DefaultHandlerExpand(data)
599
600 This is the same as the :func:`DefaultHandler`, but doesn't inhibit expansion
601 of internal entities. The entity reference will not be passed to the default
602 handler.
603
604
605 .. method:: xmlparser.NotStandaloneHandler()
606
607 Called if the XML document hasn't been declared as being a standalone document.
608 This happens when there is an external subset or a reference to a parameter
609 entity, but the XML declaration does not set standalone to ``yes`` in an XML
610 declaration. If this handler returns ``0``, then the parser will raise an
611 :const:`XML_ERROR_NOT_STANDALONE` error. If this handler is not set, no
612 exception is raised by the parser for this condition.
613
614
615 .. method:: xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)
616
617 .. warning::
618
619 Implementing a handler that accesses local files and/or the network
620 may create a vulnerability to
621 `external entity attacks <https://en.wikipedia.org/wiki/XML_external_entity_attack>`_
622 if :class:`xmlparser` is used with user-provided XML content.
623 Please reflect on your `threat model <https://en.wikipedia.org/wiki/Threat_model>`_
624 before implementing this handler.
625
626 Called for references to external entities. *base* is the current base, as set
627 by a previous call to :meth:`SetBase`. The public and system identifiers,
628 *systemId* and *publicId*, are strings if given; if the public identifier is not
629 given, *publicId* will be ``None``. The *context* value is opaque and should
630 only be used as described below.
631
632 For external entities to be parsed, this handler must be implemented. It is
633 responsible for creating the sub-parser using
634 ``ExternalEntityParserCreate(context)``, initializing it with the appropriate
635 callbacks, and parsing the entity. This handler should return an integer; if it
636 returns ``0``, the parser will raise an
637 :const:`XML_ERROR_EXTERNAL_ENTITY_HANDLING` error, otherwise parsing will
638 continue.
639
640 If this handler is not provided, external entities are reported by the
641 :attr:`DefaultHandler` callback, if provided.
642
643
644 .. _expaterror-objects:
645
646 ExpatError Exceptions
647 ---------------------
648
649 .. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
650
651
652 :exc:`ExpatError` exceptions have a number of interesting attributes:
653
654
655 .. attribute:: ExpatError.code
656
657 Expat's internal error number for the specific error. The
658 :data:`errors.messages <xml.parsers.expat.errors.messages>` dictionary maps
659 these error numbers to Expat's error messages. For example::
660
661 from xml.parsers.expat import ParserCreate, ExpatError, errors
662
663 p = ParserCreate()
664 try:
665 p.Parse(some_xml_document)
666 except ExpatError as err:
667 print("Error:", errors.messages[err.code])
668
669 The :mod:`~xml.parsers.expat.errors` module also provides error message
670 constants and a dictionary :data:`~xml.parsers.expat.errors.codes` mapping
671 these messages back to the error codes, see below.
672
673
674 .. attribute:: ExpatError.lineno
675
676 Line number on which the error was detected. The first line is numbered ``1``.
677
678
679 .. attribute:: ExpatError.offset
680
681 Character offset into the line where the error occurred. The first column is
682 numbered ``0``.
683
684
685 .. _expat-example:
686
687 Example
688 -------
689
690 The following program defines three handlers that just print out their
691 arguments. ::
692
693 import xml.parsers.expat
694
695 # 3 handler functions
696 def start_element(name, attrs):
697 print('Start element:', name, attrs)
698 def end_element(name):
699 print('End element:', name)
700 def char_data(data):
701 print('Character data:', repr(data))
702
703 p = xml.parsers.expat.ParserCreate()
704
705 p.StartElementHandler = start_element
706 p.EndElementHandler = end_element
707 p.CharacterDataHandler = char_data
708
709 p.Parse("""<?xml version="1.0"?>
710 <parent id="top"><child1 name="paul">Text goes here</child1>
711 <child2 name="fred">More text</child2>
712 </parent>""", 1)
713
714 The output from this program is::
715
716 Start element: parent {'id': 'top'}
717 Start element: child1 {'name': 'paul'}
718 Character data: 'Text goes here'
719 End element: child1
720 Character data: '\n'
721 Start element: child2 {'name': 'fred'}
722 Character data: 'More text'
723 End element: child2
724 Character data: '\n'
725 End element: parent
726
727
728 .. _expat-content-models:
729
730 Content Model Descriptions
731 --------------------------
732
733 .. module:: xml.parsers.expat.model
734
735 .. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
736
737 Content models are described using nested tuples. Each tuple contains four
738 values: the type, the quantifier, the name, and a tuple of children. Children
739 are simply additional content model descriptions.
740
741 The values of the first two fields are constants defined in the
742 :mod:`!xml.parsers.expat.model` module. These constants can be collected in two
743 groups: the model type group and the quantifier group.
744
745 The constants in the model type group are:
746
747
748 .. data:: XML_CTYPE_ANY
749 :noindex:
750
751 The element named by the model name was declared to have a content model of
752 ``ANY``.
753
754
755 .. data:: XML_CTYPE_CHOICE
756 :noindex:
757
758 The named element allows a choice from a number of options; this is used for
759 content models such as ``(A | B | C)``.
760
761
762 .. data:: XML_CTYPE_EMPTY
763 :noindex:
764
765 Elements which are declared to be ``EMPTY`` have this model type.
766
767
768 .. data:: XML_CTYPE_MIXED
769 :noindex:
770
771
772 .. data:: XML_CTYPE_NAME
773 :noindex:
774
775
776 .. data:: XML_CTYPE_SEQ
777 :noindex:
778
779 Models which represent a series of models which follow one after the other are
780 indicated with this model type. This is used for models such as ``(A, B, C)``.
781
782 The constants in the quantifier group are:
783
784
785 .. data:: XML_CQUANT_NONE
786 :noindex:
787
788 No modifier is given, so it can appear exactly once, as for ``A``.
789
790
791 .. data:: XML_CQUANT_OPT
792 :noindex:
793
794 The model is optional: it can appear once or not at all, as for ``A?``.
795
796
797 .. data:: XML_CQUANT_PLUS
798 :noindex:
799
800 The model must occur one or more times (like ``A+``).
801
802
803 .. data:: XML_CQUANT_REP
804 :noindex:
805
806 The model must occur zero or more times, as for ``A*``.
807
808
809 .. _expat-errors:
810
811 Expat error constants
812 ---------------------
813
814 .. module:: xml.parsers.expat.errors
815
816 The following constants are provided in the :mod:`!xml.parsers.expat.errors`
817 module. These constants are useful in interpreting some of the attributes of
818 the :exc:`ExpatError` exception objects raised when an error has occurred.
819 Since for backwards compatibility reasons, the constants' value is the error
820 *message* and not the numeric error *code*, you do this by comparing its
821 :attr:`code` attribute with
822 :samp:`errors.codes[errors.XML_ERROR_{CONSTANT_NAME}]`.
823
824 The ``errors`` module has the following attributes:
825
826 .. data:: codes
827
828 A dictionary mapping string descriptions to their error codes.
829
830 .. versionadded:: 3.2
831
832
833 .. data:: messages
834
835 A dictionary mapping numeric error codes to their string descriptions.
836
837 .. versionadded:: 3.2
838
839
840 .. data:: XML_ERROR_ASYNC_ENTITY
841
842
843 .. data:: XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF
844
845 An entity reference in an attribute value referred to an external entity instead
846 of an internal entity.
847
848
849 .. data:: XML_ERROR_BAD_CHAR_REF
850
851 A character reference referred to a character which is illegal in XML (for
852 example, character ``0``, or '``&#0;``').
853
854
855 .. data:: XML_ERROR_BINARY_ENTITY_REF
856
857 An entity reference referred to an entity which was declared with a notation, so
858 cannot be parsed.
859
860
861 .. data:: XML_ERROR_DUPLICATE_ATTRIBUTE
862
863 An attribute was used more than once in a start tag.
864
865
866 .. data:: XML_ERROR_INCORRECT_ENCODING
867
868
869 .. data:: XML_ERROR_INVALID_TOKEN
870
871 Raised when an input byte could not properly be assigned to a character; for
872 example, a NUL byte (value ``0``) in a UTF-8 input stream.
873
874
875 .. data:: XML_ERROR_JUNK_AFTER_DOC_ELEMENT
876
877 Something other than whitespace occurred after the document element.
878
879
880 .. data:: XML_ERROR_MISPLACED_XML_PI
881
882 An XML declaration was found somewhere other than the start of the input data.
883
884
885 .. data:: XML_ERROR_NO_ELEMENTS
886
887 The document contains no elements (XML requires all documents to contain exactly
888 one top-level element)..
889
890
891 .. data:: XML_ERROR_NO_MEMORY
892
893 Expat was not able to allocate memory internally.
894
895
896 .. data:: XML_ERROR_PARAM_ENTITY_REF
897
898 A parameter entity reference was found where it was not allowed.
899
900
901 .. data:: XML_ERROR_PARTIAL_CHAR
902
903 An incomplete character was found in the input.
904
905
906 .. data:: XML_ERROR_RECURSIVE_ENTITY_REF
907
908 An entity reference contained another reference to the same entity; possibly via
909 a different name, and possibly indirectly.
910
911
912 .. data:: XML_ERROR_SYNTAX
913
914 Some unspecified syntax error was encountered.
915
916
917 .. data:: XML_ERROR_TAG_MISMATCH
918
919 An end tag did not match the innermost open start tag.
920
921
922 .. data:: XML_ERROR_UNCLOSED_TOKEN
923
924 Some token (such as a start tag) was not closed before the end of the stream or
925 the next token was encountered.
926
927
928 .. data:: XML_ERROR_UNDEFINED_ENTITY
929
930 A reference was made to an entity which was not defined.
931
932
933 .. data:: XML_ERROR_UNKNOWN_ENCODING
934
935 The document encoding is not supported by Expat.
936
937
938 .. data:: XML_ERROR_UNCLOSED_CDATA_SECTION
939
940 A CDATA marked section was not closed.
941
942
943 .. data:: XML_ERROR_EXTERNAL_ENTITY_HANDLING
944
945
946 .. data:: XML_ERROR_NOT_STANDALONE
947
948 The parser determined that the document was not "standalone" though it declared
949 itself to be in the XML declaration, and the :attr:`NotStandaloneHandler` was
950 set and returned ``0``.
951
952
953 .. data:: XML_ERROR_UNEXPECTED_STATE
954
955
956 .. data:: XML_ERROR_ENTITY_DECLARED_IN_PE
957
958
959 .. data:: XML_ERROR_FEATURE_REQUIRES_XML_DTD
960
961 An operation was requested that requires DTD support to be compiled in, but
962 Expat was configured without DTD support. This should never be reported by a
963 standard build of the :mod:`!xml.parsers.expat` module.
964
965
966 .. data:: XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING
967
968 A behavioral change was requested after parsing started that can only be changed
969 before parsing has started. This is (currently) only raised by
970 :meth:`UseForeignDTD`.
971
972
973 .. data:: XML_ERROR_UNBOUND_PREFIX
974
975 An undeclared prefix was found when namespace processing was enabled.
976
977
978 .. data:: XML_ERROR_UNDECLARING_PREFIX
979
980 The document attempted to remove the namespace declaration associated with a
981 prefix.
982
983
984 .. data:: XML_ERROR_INCOMPLETE_PE
985
986 A parameter entity contained incomplete markup.
987
988
989 .. data:: XML_ERROR_XML_DECL
990
991 The document contained no document element at all.
992
993
994 .. data:: XML_ERROR_TEXT_DECL
995
996 There was an error parsing a text declaration in an external entity.
997
998
999 .. data:: XML_ERROR_PUBLICID
1000
1001 Characters were found in the public id that are not allowed.
1002
1003
1004 .. data:: XML_ERROR_SUSPENDED
1005
1006 The requested operation was made on a suspended parser, but isn't allowed. This
1007 includes attempts to provide additional input or to stop the parser.
1008
1009
1010 .. data:: XML_ERROR_NOT_SUSPENDED
1011
1012 An attempt to resume the parser was made when the parser had not been suspended.
1013
1014
1015 .. data:: XML_ERROR_ABORTED
1016
1017 This should not be reported to Python applications.
1018
1019
1020 .. data:: XML_ERROR_FINISHED
1021
1022 The requested operation was made on a parser which was finished parsing input,
1023 but isn't allowed. This includes attempts to provide additional input or to
1024 stop the parser.
1025
1026
1027 .. data:: XML_ERROR_SUSPEND_PE
1028
1029
1030 .. data:: XML_ERROR_RESERVED_PREFIX_XML
1031
1032 An attempt was made to
1033 undeclare reserved namespace prefix ``xml``
1034 or to bind it to another namespace URI.
1035
1036
1037 .. data:: XML_ERROR_RESERVED_PREFIX_XMLNS
1038
1039 An attempt was made to declare or undeclare reserved namespace prefix ``xmlns``.
1040
1041
1042 .. data:: XML_ERROR_RESERVED_NAMESPACE_URI
1043
1044 An attempt was made to bind the URI of one the reserved namespace
1045 prefixes ``xml`` and ``xmlns`` to another namespace prefix.
1046
1047
1048 .. data:: XML_ERROR_INVALID_ARGUMENT
1049
1050 This should not be reported to Python applications.
1051
1052
1053 .. data:: XML_ERROR_NO_BUFFER
1054
1055 This should not be reported to Python applications.
1056
1057
1058 .. data:: XML_ERROR_AMPLIFICATION_LIMIT_BREACH
1059
1060 The limit on input amplification factor (from DTD and entities)
1061 has been breached.
1062
1063
1064 .. data:: XML_ERROR_NOT_STARTED
1065
1066 The parser was tried to be stopped or suspended before it started.
1067
1068 .. versionadded:: 3.14
1069
1070
1071 .. rubric:: Footnotes
1072
1073 .. [1] The encoding string included in XML output should conform to the
1074 appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
1075 not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
1076 and https://www.iana.org/assignments/character-sets/character-sets.xhtml.
1077
1078
1079 .. _billion laughs: https://en.wikipedia.org/wiki/Billion_laughs_attack
1080 .. |xml-non-root-parser| replace:: :ref:`non-root <xmlparser-non-root>`