/Doc/library/pyexpat.rst
ReStructuredText | 895 lines | 534 code | 361 blank | 0 comment | 0 complexity | bd7cd540872d40aa041e1e4623c5c458 MD5 | raw file
1 2:mod:`xml.parsers.expat` --- Fast XML parsing using Expat 3========================================================= 4 5.. module:: xml.parsers.expat 6 :synopsis: An interface to the Expat non-validating XML parser. 7.. moduleauthor:: Paul Prescod <paul@prescod.net> 8 9 10.. Markup notes: 11 12 Many of the attributes of the XMLParser objects are callbacks. Since 13 signature information must be presented, these are described using the method 14 directive. Since they are attributes which are set by client code, in-text 15 references to these attributes should be marked using the :member: role. 16 17.. versionadded:: 2.0 18 19.. index:: single: Expat 20 21The :mod:`xml.parsers.expat` module is a Python interface to the Expat 22non-validating XML parser. The module provides a single extension type, 23:class:`xmlparser`, that represents the current state of an XML parser. After 24an :class:`xmlparser` object has been created, various attributes of the object 25can be set to handler functions. When an XML document is then fed to the 26parser, the handler functions are called for the character data and markup in 27the XML document. 28 29.. index:: module: pyexpat 30 31This module uses the :mod:`pyexpat` module to provide access to the Expat 32parser. Direct use of the :mod:`pyexpat` module is deprecated. 33 34This module provides one exception and one type object: 35 36 37.. exception:: ExpatError 38 39 The exception raised when Expat reports an error. See section 40 :ref:`expaterror-objects` for more information on interpreting Expat errors. 41 42 43.. exception:: error 44 45 Alias for :exc:`ExpatError`. 46 47 48.. data:: XMLParserType 49 50 The type of the return values from the :func:`ParserCreate` function. 51 52The :mod:`xml.parsers.expat` module contains two functions: 53 54 55.. function:: ErrorString(errno) 56 57 Returns an explanatory string for a given error number *errno*. 58 59 60.. function:: ParserCreate([encoding[, namespace_separator]]) 61 62 Creates and returns a new :class:`xmlparser` object. *encoding*, if specified, 63 must be a string naming the encoding used by the XML data. Expat doesn't 64 support as many encodings as Python does, and its repertoire of encodings can't 65 be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If 66 *encoding* [1]_ is given it will override the implicit or explicit encoding of the 67 document. 68 69 Expat can optionally do XML namespace processing for you, enabled by providing a 70 value for *namespace_separator*. The value must be a one-character string; a 71 :exc:`ValueError` will be raised if the string has an illegal length (``None`` 72 is considered the same as omission). When namespace processing is enabled, 73 element type names and attribute names that belong to a namespace will be 74 expanded. The element name passed to the element handlers 75 :attr:`StartElementHandler` and :attr:`EndElementHandler` will be the 76 concatenation of the namespace URI, the namespace separator character, and the 77 local part of the name. If the namespace separator is a zero byte (``chr(0)``) 78 then the namespace URI and the local part will be concatenated without any 79 separator. 80 81 For example, if *namespace_separator* is set to a space character (``' '``) and 82 the following document is parsed:: 83 84 <?xml version="1.0"?> 85 <root xmlns = "http://default-namespace.org/" 86 xmlns:py = "http://www.python.org/ns/"> 87 <py:elem1 /> 88 <elem2 xmlns="" /> 89 </root> 90 91 :attr:`StartElementHandler` will receive the following strings for each 92 element:: 93 94 http://default-namespace.org/ root 95 http://www.python.org/ns/ elem1 96 elem2 97 98 99.. seealso:: 100 101 `The Expat XML Parser <http://www.libexpat.org/>`_ 102 Home page of the Expat project. 103 104 105.. _xmlparser-objects: 106 107XMLParser Objects 108----------------- 109 110:class:`xmlparser` objects have the following methods: 111 112 113.. method:: xmlparser.Parse(data[, isfinal]) 114 115 Parses the contents of the string *data*, calling the appropriate handler 116 functions to process the parsed data. *isfinal* must be true on the final call 117 to this method. *data* can be the empty string at any time. 118 119 120.. method:: xmlparser.ParseFile(file) 121 122 Parse XML data reading from the object *file*. *file* only needs to provide 123 the ``read(nbytes)`` method, returning the empty string when there's no more 124 data. 125 126 127.. method:: xmlparser.SetBase(base) 128 129 Sets the base to be used for resolving relative URIs in system identifiers in 130 declarations. Resolving relative identifiers is left to the application: this 131 value will be passed through as the *base* argument to the 132 :func:`ExternalEntityRefHandler`, :func:`NotationDeclHandler`, and 133 :func:`UnparsedEntityDeclHandler` functions. 134 135 136.. method:: xmlparser.GetBase() 137 138 Returns a string containing the base set by a previous call to :meth:`SetBase`, 139 or ``None`` if :meth:`SetBase` hasn't been called. 140 141 142.. method:: xmlparser.GetInputContext() 143 144 Returns the input data that generated the current event as a string. The data is 145 in the encoding of the entity which contains the text. When called while an 146 event handler is not active, the return value is ``None``. 147 148 .. versionadded:: 2.1 149 150 151.. method:: xmlparser.ExternalEntityParserCreate(context[, encoding]) 152 153 Create a "child" parser which can be used to parse an external parsed entity 154 referred to by content parsed by the parent parser. The *context* parameter 155 should be the string passed to the :meth:`ExternalEntityRefHandler` handler 156 function, described below. The child parser is created with the 157 :attr:`ordered_attributes`, :attr:`returns_unicode` and 158 :attr:`specified_attributes` set to the values of this parser. 159 160 161.. method:: xmlparser.UseForeignDTD([flag]) 162 163 Calling this with a true value for *flag* (the default) will cause Expat to call 164 the :attr:`ExternalEntityRefHandler` with :const:`None` for all arguments to 165 allow an alternate DTD to be loaded. If the document does not contain a 166 document type declaration, the :attr:`ExternalEntityRefHandler` will still be 167 called, but the :attr:`StartDoctypeDeclHandler` and 168 :attr:`EndDoctypeDeclHandler` will not be called. 169 170 Passing a false value for *flag* will cancel a previous call that passed a true 171 value, but otherwise has no effect. 172 173 This method can only be called before the :meth:`Parse` or :meth:`ParseFile` 174 methods are called; calling it after either of those have been called causes 175 :exc:`ExpatError` to be raised with the :attr:`code` attribute set to 176 :const:`errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING`. 177 178 .. versionadded:: 2.3 179 180:class:`xmlparser` objects have the following attributes: 181 182 183.. attribute:: xmlparser.buffer_size 184 185 The size of the buffer used when :attr:`buffer_text` is true. 186 A new buffer size can be set by assigning a new integer value 187 to this attribute. 188 When the size is changed, the buffer will be flushed. 189 190 .. versionadded:: 2.3 191 192 .. versionchanged:: 2.6 193 The buffer size can now be changed. 194 195.. attribute:: xmlparser.buffer_text 196 197 Setting this to true causes the :class:`xmlparser` object to buffer textual 198 content returned by Expat to avoid multiple calls to the 199 :meth:`CharacterDataHandler` callback whenever possible. This can improve 200 performance substantially since Expat normally breaks character data into chunks 201 at every line ending. This attribute is false by default, and may be changed at 202 any time. 203 204 .. versionadded:: 2.3 205 206 207.. attribute:: xmlparser.buffer_used 208 209 If :attr:`buffer_text` is enabled, the number of bytes stored in the buffer. 210 These bytes represent UTF-8 encoded text. This attribute has no meaningful 211 interpretation when :attr:`buffer_text` is false. 212 213 .. versionadded:: 2.3 214 215 216.. attribute:: xmlparser.ordered_attributes 217 218 Setting this attribute to a non-zero integer causes the attributes to be 219 reported as a list rather than a dictionary. The attributes are presented in 220 the order found in the document text. For each attribute, two list entries are 221 presented: the attribute name and the attribute value. (Older versions of this 222 module also used this format.) By default, this attribute is false; it may be 223 changed at any time. 224 225 .. versionadded:: 2.1 226 227 228.. attribute:: xmlparser.returns_unicode 229 230 If this attribute is set to a non-zero integer, the handler functions will be 231 passed Unicode strings. If :attr:`returns_unicode` is :const:`False`, 8-bit 232 strings containing UTF-8 encoded data will be passed to the handlers. This is 233 :const:`True` by default when Python is built with Unicode support. 234 235 .. versionchanged:: 1.6 236 Can be changed at any time to affect the result type. 237 238 239.. attribute:: xmlparser.specified_attributes 240 241 If set to a non-zero integer, the parser will report only those attributes which 242 were specified in the document instance and not those which were derived from 243 attribute declarations. Applications which set this need to be especially 244 careful to use what additional information is available from the declarations as 245 needed to comply with the standards for the behavior of XML processors. By 246 default, this attribute is false; it may be changed at any time. 247 248 .. versionadded:: 2.1 249 250The following attributes contain values relating to the most recent error 251encountered by an :class:`xmlparser` object, and will only have correct values 252once a call to :meth:`Parse` or :meth:`ParseFile` has raised a 253:exc:`xml.parsers.expat.ExpatError` exception. 254 255 256.. attribute:: xmlparser.ErrorByteIndex 257 258 Byte index at which an error occurred. 259 260 261.. attribute:: xmlparser.ErrorCode 262 263 Numeric code specifying the problem. This value can be passed to the 264 :func:`ErrorString` function, or compared to one of the constants defined in the 265 ``errors`` object. 266 267 268.. attribute:: xmlparser.ErrorColumnNumber 269 270 Column number at which an error occurred. 271 272 273.. attribute:: xmlparser.ErrorLineNumber 274 275 Line number at which an error occurred. 276 277The following attributes contain values relating to the current parse location 278in an :class:`xmlparser` object. During a callback reporting a parse event they 279indicate the location of the first of the sequence of characters that generated 280the event. When called outside of a callback, the position indicated will be 281just past the last parse event (regardless of whether there was an associated 282callback). 283 284.. versionadded:: 2.4 285 286 287.. attribute:: xmlparser.CurrentByteIndex 288 289 Current byte index in the parser input. 290 291 292.. attribute:: xmlparser.CurrentColumnNumber 293 294 Current column number in the parser input. 295 296 297.. attribute:: xmlparser.CurrentLineNumber 298 299 Current line number in the parser input. 300 301Here is the list of handlers that can be set. To set a handler on an 302:class:`xmlparser` object *o*, use ``o.handlername = func``. *handlername* must 303be taken from the following list, and *func* must be a callable object accepting 304the correct number of arguments. The arguments are all strings, unless 305otherwise stated. 306 307 308.. method:: xmlparser.XmlDeclHandler(version, encoding, standalone) 309 310 Called when the XML declaration is parsed. The XML declaration is the 311 (optional) declaration of the applicable version of the XML recommendation, the 312 encoding of the document text, and an optional "standalone" declaration. 313 *version* and *encoding* will be strings of the type dictated by the 314 :attr:`returns_unicode` attribute, and *standalone* will be ``1`` if the 315 document is declared standalone, ``0`` if it is declared not to be standalone, 316 or ``-1`` if the standalone clause was omitted. This is only available with 317 Expat version 1.95.0 or newer. 318 319 .. versionadded:: 2.1 320 321 322.. method:: xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset) 323 324 Called when Expat begins parsing the document type declaration (``<!DOCTYPE 325 ...``). The *doctypeName* is provided exactly as presented. The *systemId* and 326 *publicId* parameters give the system and public identifiers if specified, or 327 ``None`` if omitted. *has_internal_subset* will be true if the document 328 contains and internal document declaration subset. This requires Expat version 329 1.2 or newer. 330 331 332.. method:: xmlparser.EndDoctypeDeclHandler() 333 334 Called when Expat is done parsing the document type declaration. This requires 335 Expat version 1.2 or newer. 336 337 338.. method:: xmlparser.ElementDeclHandler(name, model) 339 340 Called once for each element type declaration. *name* is the name of the 341 element type, and *model* is a representation of the content model. 342 343 344.. method:: xmlparser.AttlistDeclHandler(elname, attname, type, default, required) 345 346 Called for each declared attribute for an element type. If an attribute list 347 declaration declares three attributes, this handler is called three times, once 348 for each attribute. *elname* is the name of the element to which the 349 declaration applies and *attname* is the name of the attribute declared. The 350 attribute type is a string passed as *type*; the possible values are 351 ``'CDATA'``, ``'ID'``, ``'IDREF'``, ... *default* gives the default value for 352 the attribute used when the attribute is not specified by the document instance, 353 or ``None`` if there is no default value (``#IMPLIED`` values). If the 354 attribute is required to be given in the document instance, *required* will be 355 true. This requires Expat version 1.95.0 or newer. 356 357 358.. method:: xmlparser.StartElementHandler(name, attributes) 359 360 Called for the start of every element. *name* is a string containing the 361 element name, and *attributes* is a dictionary mapping attribute names to their 362 values. 363 364 365.. method:: xmlparser.EndElementHandler(name) 366 367 Called for the end of every element. 368 369 370.. method:: xmlparser.ProcessingInstructionHandler(target, data) 371 372 Called for every processing instruction. 373 374 375.. method:: xmlparser.CharacterDataHandler(data) 376 377 Called for character data. This will be called for normal character data, CDATA 378 marked content, and ignorable whitespace. Applications which must distinguish 379 these cases can use the :attr:`StartCdataSectionHandler`, 380 :attr:`EndCdataSectionHandler`, and :attr:`ElementDeclHandler` callbacks to 381 collect the required information. 382 383 384.. method:: xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName) 385 386 Called for unparsed (NDATA) entity declarations. This is only present for 387 version 1.2 of the Expat library; for more recent versions, use 388 :attr:`EntityDeclHandler` instead. (The underlying function in the Expat 389 library has been declared obsolete.) 390 391 392.. method:: xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName) 393 394 Called for all entity declarations. For parameter and internal entities, 395 *value* will be a string giving the declared contents of the entity; this will 396 be ``None`` for external entities. The *notationName* parameter will be 397 ``None`` for parsed entities, and the name of the notation for unparsed 398 entities. *is_parameter_entity* will be true if the entity is a parameter entity 399 or false for general entities (most applications only need to be concerned with 400 general entities). This is only available starting with version 1.95.0 of the 401 Expat library. 402 403 .. versionadded:: 2.1 404 405 406.. method:: xmlparser.NotationDeclHandler(notationName, base, systemId, publicId) 407 408 Called for notation declarations. *notationName*, *base*, and *systemId*, and 409 *publicId* are strings if given. If the public identifier is omitted, 410 *publicId* will be ``None``. 411 412 413.. method:: xmlparser.StartNamespaceDeclHandler(prefix, uri) 414 415 Called when an element contains a namespace declaration. Namespace declarations 416 are processed before the :attr:`StartElementHandler` is called for the element 417 on which declarations are placed. 418 419 420.. method:: xmlparser.EndNamespaceDeclHandler(prefix) 421 422 Called when the closing tag is reached for an element that contained a 423 namespace declaration. This is called once for each namespace declaration on 424 the element in the reverse of the order for which the 425 :attr:`StartNamespaceDeclHandler` was called to indicate the start of each 426 namespace declaration's scope. Calls to this handler are made after the 427 corresponding :attr:`EndElementHandler` for the end of the element. 428 429 430.. method:: xmlparser.CommentHandler(data) 431 432 Called for comments. *data* is the text of the comment, excluding the leading 433 '``<!-``\ ``-``' and trailing '``-``\ ``->``'. 434 435 436.. method:: xmlparser.StartCdataSectionHandler() 437 438 Called at the start of a CDATA section. This and :attr:`EndCdataSectionHandler` 439 are needed to be able to identify the syntactical start and end for CDATA 440 sections. 441 442 443.. method:: xmlparser.EndCdataSectionHandler() 444 445 Called at the end of a CDATA section. 446 447 448.. method:: xmlparser.DefaultHandler(data) 449 450 Called for any characters in the XML document for which no applicable handler 451 has been specified. This means characters that are part of a construct which 452 could be reported, but for which no handler has been supplied. 453 454 455.. method:: xmlparser.DefaultHandlerExpand(data) 456 457 This is the same as the :func:`DefaultHandler`, but doesn't inhibit expansion 458 of internal entities. The entity reference will not be passed to the default 459 handler. 460 461 462.. method:: xmlparser.NotStandaloneHandler() 463 464 Called if the XML document hasn't been declared as being a standalone document. 465 This happens when there is an external subset or a reference to a parameter 466 entity, but the XML declaration does not set standalone to ``yes`` in an XML 467 declaration. If this handler returns ``0``, then the parser will throw an 468 :const:`XML_ERROR_NOT_STANDALONE` error. If this handler is not set, no 469 exception is raised by the parser for this condition. 470 471 472.. method:: xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId) 473 474 Called for references to external entities. *base* is the current base, as set 475 by a previous call to :meth:`SetBase`. The public and system identifiers, 476 *systemId* and *publicId*, are strings if given; if the public identifier is not 477 given, *publicId* will be ``None``. The *context* value is opaque and should 478 only be used as described below. 479 480 For external entities to be parsed, this handler must be implemented. It is 481 responsible for creating the sub-parser using 482 ``ExternalEntityParserCreate(context)``, initializing it with the appropriate 483 callbacks, and parsing the entity. This handler should return an integer; if it 484 returns ``0``, the parser will throw an 485 :const:`XML_ERROR_EXTERNAL_ENTITY_HANDLING` error, otherwise parsing will 486 continue. 487 488 If this handler is not provided, external entities are reported by the 489 :attr:`DefaultHandler` callback, if provided. 490 491 492.. _expaterror-objects: 493 494ExpatError Exceptions 495--------------------- 496 497.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 498 499 500:exc:`ExpatError` exceptions have a number of interesting attributes: 501 502 503.. attribute:: ExpatError.code 504 505 Expat's internal error number for the specific error. This will match one of 506 the constants defined in the ``errors`` object from this module. 507 508 .. versionadded:: 2.1 509 510 511.. attribute:: ExpatError.lineno 512 513 Line number on which the error was detected. The first line is numbered ``1``. 514 515 .. versionadded:: 2.1 516 517 518.. attribute:: ExpatError.offset 519 520 Character offset into the line where the error occurred. The first column is 521 numbered ``0``. 522 523 .. versionadded:: 2.1 524 525 526.. _expat-example: 527 528Example 529------- 530 531The following program defines three handlers that just print out their 532arguments. :: 533 534 import xml.parsers.expat 535 536 # 3 handler functions 537 def start_element(name, attrs): 538 print 'Start element:', name, attrs 539 def end_element(name): 540 print 'End element:', name 541 def char_data(data): 542 print 'Character data:', repr(data) 543 544 p = xml.parsers.expat.ParserCreate() 545 546 p.StartElementHandler = start_element 547 p.EndElementHandler = end_element 548 p.CharacterDataHandler = char_data 549 550 p.Parse("""<?xml version="1.0"?> 551 <parent id="top"><child1 name="paul">Text goes here</child1> 552 <child2 name="fred">More text</child2> 553 </parent>""", 1) 554 555The output from this program is:: 556 557 Start element: parent {'id': 'top'} 558 Start element: child1 {'name': 'paul'} 559 Character data: 'Text goes here' 560 End element: child1 561 Character data: '\n' 562 Start element: child2 {'name': 'fred'} 563 Character data: 'More text' 564 End element: child2 565 Character data: '\n' 566 End element: parent 567 568 569.. _expat-content-models: 570 571Content Model Descriptions 572-------------------------- 573 574.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 575 576 577Content modules are described using nested tuples. Each tuple contains four 578values: the type, the quantifier, the name, and a tuple of children. Children 579are simply additional content module descriptions. 580 581The values of the first two fields are constants defined in the ``model`` object 582of the :mod:`xml.parsers.expat` module. These constants can be collected in two 583groups: the model type group and the quantifier group. 584 585The constants in the model type group are: 586 587 588.. data:: XML_CTYPE_ANY 589 :noindex: 590 591 The element named by the model name was declared to have a content model of 592 ``ANY``. 593 594 595.. data:: XML_CTYPE_CHOICE 596 :noindex: 597 598 The named element allows a choice from a number of options; this is used for 599 content models such as ``(A | B | C)``. 600 601 602.. data:: XML_CTYPE_EMPTY 603 :noindex: 604 605 Elements which are declared to be ``EMPTY`` have this model type. 606 607 608.. data:: XML_CTYPE_MIXED 609 :noindex: 610 611 612.. data:: XML_CTYPE_NAME 613 :noindex: 614 615 616.. data:: XML_CTYPE_SEQ 617 :noindex: 618 619 Models which represent a series of models which follow one after the other are 620 indicated with this model type. This is used for models such as ``(A, B, C)``. 621 622The constants in the quantifier group are: 623 624 625.. data:: XML_CQUANT_NONE 626 :noindex: 627 628 No modifier is given, so it can appear exactly once, as for ``A``. 629 630 631.. data:: XML_CQUANT_OPT 632 :noindex: 633 634 The model is optional: it can appear once or not at all, as for ``A?``. 635 636 637.. data:: XML_CQUANT_PLUS 638 :noindex: 639 640 The model must occur one or more times (like ``A+``). 641 642 643.. data:: XML_CQUANT_REP 644 :noindex: 645 646 The model must occur zero or more times, as for ``A*``. 647 648 649.. _expat-errors: 650 651Expat error constants 652--------------------- 653 654The following constants are provided in the ``errors`` object of the 655:mod:`xml.parsers.expat` module. These constants are useful in interpreting 656some of the attributes of the :exc:`ExpatError` exception objects raised when an 657error has occurred. 658 659The ``errors`` object has the following attributes: 660 661 662.. data:: XML_ERROR_ASYNC_ENTITY 663 :noindex: 664 665 666.. data:: XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF 667 :noindex: 668 669 An entity reference in an attribute value referred to an external entity instead 670 of an internal entity. 671 672 673.. data:: XML_ERROR_BAD_CHAR_REF 674 :noindex: 675 676 A character reference referred to a character which is illegal in XML (for 677 example, character ``0``, or '``�``'). 678 679 680.. data:: XML_ERROR_BINARY_ENTITY_REF 681 :noindex: 682 683 An entity reference referred to an entity which was declared with a notation, so 684 cannot be parsed. 685 686 687.. data:: XML_ERROR_DUPLICATE_ATTRIBUTE 688 :noindex: 689 690 An attribute was used more than once in a start tag. 691 692 693.. data:: XML_ERROR_INCORRECT_ENCODING 694 :noindex: 695 696 697.. data:: XML_ERROR_INVALID_TOKEN 698 :noindex: 699 700 Raised when an input byte could not properly be assigned to a character; for 701 example, a NUL byte (value ``0``) in a UTF-8 input stream. 702 703 704.. data:: XML_ERROR_JUNK_AFTER_DOC_ELEMENT 705 :noindex: 706 707 Something other than whitespace occurred after the document element. 708 709 710.. data:: XML_ERROR_MISPLACED_XML_PI 711 :noindex: 712 713 An XML declaration was found somewhere other than the start of the input data. 714 715 716.. data:: XML_ERROR_NO_ELEMENTS 717 :noindex: 718 719 The document contains no elements (XML requires all documents to contain exactly 720 one top-level element).. 721 722 723.. data:: XML_ERROR_NO_MEMORY 724 :noindex: 725 726 Expat was not able to allocate memory internally. 727 728 729.. data:: XML_ERROR_PARAM_ENTITY_REF 730 :noindex: 731 732 A parameter entity reference was found where it was not allowed. 733 734 735.. data:: XML_ERROR_PARTIAL_CHAR 736 :noindex: 737 738 An incomplete character was found in the input. 739 740 741.. data:: XML_ERROR_RECURSIVE_ENTITY_REF 742 :noindex: 743 744 An entity reference contained another reference to the same entity; possibly via 745 a different name, and possibly indirectly. 746 747 748.. data:: XML_ERROR_SYNTAX 749 :noindex: 750 751 Some unspecified syntax error was encountered. 752 753 754.. data:: XML_ERROR_TAG_MISMATCH 755 :noindex: 756 757 An end tag did not match the innermost open start tag. 758 759 760.. data:: XML_ERROR_UNCLOSED_TOKEN 761 :noindex: 762 763 Some token (such as a start tag) was not closed before the end of the stream or 764 the next token was encountered. 765 766 767.. data:: XML_ERROR_UNDEFINED_ENTITY 768 :noindex: 769 770 A reference was made to a entity which was not defined. 771 772 773.. data:: XML_ERROR_UNKNOWN_ENCODING 774 :noindex: 775 776 The document encoding is not supported by Expat. 777 778 779.. data:: XML_ERROR_UNCLOSED_CDATA_SECTION 780 :noindex: 781 782 A CDATA marked section was not closed. 783 784 785.. data:: XML_ERROR_EXTERNAL_ENTITY_HANDLING 786 :noindex: 787 788 789.. data:: XML_ERROR_NOT_STANDALONE 790 :noindex: 791 792 The parser determined that the document was not "standalone" though it declared 793 itself to be in the XML declaration, and the :attr:`NotStandaloneHandler` was 794 set and returned ``0``. 795 796 797.. data:: XML_ERROR_UNEXPECTED_STATE 798 :noindex: 799 800 801.. data:: XML_ERROR_ENTITY_DECLARED_IN_PE 802 :noindex: 803 804 805.. data:: XML_ERROR_FEATURE_REQUIRES_XML_DTD 806 :noindex: 807 808 An operation was requested that requires DTD support to be compiled in, but 809 Expat was configured without DTD support. This should never be reported by a 810 standard build of the :mod:`xml.parsers.expat` module. 811 812 813.. data:: XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING 814 :noindex: 815 816 A behavioral change was requested after parsing started that can only be changed 817 before parsing has started. This is (currently) only raised by 818 :meth:`UseForeignDTD`. 819 820 821.. data:: XML_ERROR_UNBOUND_PREFIX 822 :noindex: 823 824 An undeclared prefix was found when namespace processing was enabled. 825 826 827.. data:: XML_ERROR_UNDECLARING_PREFIX 828 :noindex: 829 830 The document attempted to remove the namespace declaration associated with a 831 prefix. 832 833 834.. data:: XML_ERROR_INCOMPLETE_PE 835 :noindex: 836 837 A parameter entity contained incomplete markup. 838 839 840.. data:: XML_ERROR_XML_DECL 841 :noindex: 842 843 The document contained no document element at all. 844 845 846.. data:: XML_ERROR_TEXT_DECL 847 :noindex: 848 849 There was an error parsing a text declaration in an external entity. 850 851 852.. data:: XML_ERROR_PUBLICID 853 :noindex: 854 855 Characters were found in the public id that are not allowed. 856 857 858.. data:: XML_ERROR_SUSPENDED 859 :noindex: 860 861 The requested operation was made on a suspended parser, but isn't allowed. This 862 includes attempts to provide additional input or to stop the parser. 863 864 865.. data:: XML_ERROR_NOT_SUSPENDED 866 :noindex: 867 868 An attempt to resume the parser was made when the parser had not been suspended. 869 870 871.. data:: XML_ERROR_ABORTED 872 :noindex: 873 874 This should not be reported to Python applications. 875 876 877.. data:: XML_ERROR_FINISHED 878 :noindex: 879 880 The requested operation was made on a parser which was finished parsing input, 881 but isn't allowed. This includes attempts to provide additional input or to 882 stop the parser. 883 884 885.. data:: XML_ERROR_SUSPEND_PE 886 :noindex: 887 888 889.. rubric:: Footnotes 890 891.. [#] The encoding string included in XML output should conform to the 892 appropriate standards. For example, "UTF-8" is valid, but "UTF8" is 893 not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl 894 and http://www.iana.org/assignments/character-sets . 895