Text of docs.python.org › 3.16 › library › pyexpat.html as Styx crawled it on Oct 11, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

xml.parsers.expat — Fast XML parsing using Expat — Python 3.16.0a0 documentation

Navigation index modules | next | previous | Python » 3.16.0a0 Documentation » The Python standard library » Structured Markup Processing Tools » xml.parsers.expat — Fast XML parsing using Expat | Theme | xml.parsers.expat — Fast XML parsing using Expat ¶ Note If you need to parse untrusted or unauthenticated data, see XML security . The xml.parsers.expat module is a Python interface to the Expat non-validating XML parser.

The module provides a single extension type, xmlparser , that represents the current state of an XML parser. After an xmlparser object has been created, various attributes of the object can be set to handler functions. When an XML document is then fed to the parser, the handler functions are called for the character data and markup in the XML document. This module uses the pyexpat module to provide access to the Expat parser.

Direct use of the pyexpat module is deprecated. This module provides the following exception, type object and data items: exception xml.parsers.expat. ExpatError ¶ The exception raised when Expat reports an error. See section ExpatError Exceptions for more information on interpreting Expat errors. exception xml.parsers.expat. error ¶ Alias for ExpatError . xml.parsers.expat. XMLParserType ¶ The type of the return values from the ParserCreate() function. xml.parsers.expat.

EXPAT_VERSION ¶ The version string of the Expat library loaded by the interpreter, like 'expat_2.8.4' . xml.parsers.expat. VERSION_INFO ¶ A named tuple containing the three components of the Expat library version that was used for building the module: major , minor , and micro . All values are integers. The components can also be accessed by name, so xml.parsers.expat.VERSION_INFO[0] is equivalent to xml.parsers.expat.VERSION_INFO.major and so on.

This may be different from the Expat library actually used at runtime, which is available as version_info . Added in version 3.16.0a0 (unreleased). xml.parsers.expat. version_info ¶ A named tuple containing the version of the Expat library loaded by the interpreter, with the same fields as VERSION_INFO . Changed in version 3.16.0a0 (unreleased): It is now a named tuple. xml.parsers.expat. features ¶ The list of the features with which the loaded Expat library was compiled, as (name, value) pairs.

The value is only meaningful for features which have one, like 'XML_CONTEXT_BYTES' or the default protection limits 'XML_BLAP_ACT_THRES' and 'XML_AT_MAX_AMP' ; for other features, like 'XML_DTD' and 'XML_NS' , the value is 0 and only the presence of the name is significant. The xml.parsers.expat module contains two functions: xml.parsers.expat. ErrorString ( errno ) ¶ Returns an explanatory string for a given error number errno . xml.parsers.expat.

ParserCreate ( encoding = None , namespace_separator = None , intern = None ) ¶ Creates and returns a new xmlparser object. encoding [ 1 ] , if specified, must be a string naming the encoding used by the XML data. If it is given it will override the implicit or explicit encoding of the document. CPython implementation detail: Expat natively understands and processes UTF-8, UTF-16, UTF-16BE, UTF-16LE, ISO-8859-1, and US-ASCII.

For other encodings (including aliases like Latin1 and ASCII) it falls back to Python. It supports most of 8-bit encodings and many multi-byte encodings like Shift_JIS, although only BMP characters ( U+0000-U+FFFF ) are supported with non-native encodings (this restriction is also applied to aliases like UTF8). These restrictions only apply if encoding is not given. Changed in version 3.16.0a0 (unreleased): Added support for multi-byte encodings.

Parsers created through ParserCreate() are called “root” parsers, in the sense that they do not have any parent parser attached. Non-root parsers are created by parser.ExternalEntityParserCreate . Expat can optionally do XML namespace processing for you, enabled by providing a value for namespace_separator . The value must be a one-character string; a ValueError will be raised if the string has an illegal length ( None is considered the same as omission).

When namespace processing is enabled, element type names and attribute names that belong to a namespace will be expanded. The element name passed to the element handlers StartElementHandler and EndElementHandler will be the concatenation of the namespace URI, the namespace separator character, and the local part of the name. If the namespace separator is a zero byte ( chr(0) ) then the namespace URI and the local part will be concatenated without any separator.

For example, if namespace_separator is set to a space character ( ' ' ) and the following document is parsed: <?xml version="1.0"?> <root xmlns = "http://default-namespace.org/" xmlns:py = "http://www.python.org/ns/" > <py:elem1 /> <elem2 xmlns= "" /> </root> StartElementHandler will receive the following strings for each element: http : // default - namespace . org / root http : // www . python . org / ns / elem1 elem2 intern , if given, must be a dictionary.

It is used to intern the names of elements and attributes, and is available as the intern attribute. By default a new empty dictionary is created for every parser. Due to limitations in the Expat library used by pyexpat , the xmlparser instance returned can only be used to parse a single XML document. Call ParserCreate for each document to provide unique parser instances. See also The Expat XML Parser Home page of the Expat project.

XMLParser Objects ¶ xmlparser objects have the following methods: xmlparser. Parse ( data [ , isfinal ] ) ¶ Parses the contents of data , calling the appropriate handler functions to process the parsed data. data can be a bytes-like object or a string. If it is a string, the encoding declaration in the XML data is ignored, and the data is parsed as already decoded text. isfinal must be true on the final call to this method; it allows the parsing of a single file in fragments, not the submission of multiple files. data can be empty at any time. xmlparser.

ParseFile ( file ) ¶ Parse XML data reading from the object file . file only needs to provide the read(nbytes) method, which returns bytes, and an empty bytes object when there’s no more data. Text files are not supported; use Parse() for data which is already decoded. xmlparser. SetBase ( base ) ¶ Sets the base to be used for resolving relative URIs in system identifiers in declarations. Resolving relative identifiers is left to the application: this value will be passed through as the base argument to the ExternalEntityRefHandler() , NotationDeclHandler() , and UnparsedEntityDeclHandler() functions. xmlparser.

GetBase ( ) ¶ Returns a string containing the base set by a previous call to SetBase() , or None if SetBase() hasn’t been called. xmlparser. GetSpecifiedAttributeCount ( ) ¶ Return the index just past the attributes given in the start tag. Attributes defaulted from the DTD follow the specified ones, so attributes at lower indices in the list passed to StartElementHandler were given in the start tag. Each attribute takes two items in that list, its name and its value.

Only meaningful inside a StartElementHandler call, and only if ordered_attributes is true. Added in version 3.16.0a0 (unreleased). xmlparser. GetInputContext ( ) ¶ Returns the input data which generated the current event as a bytes object. The data is in the encoding of the entity which contains the text. It extends to the end of the currently buffered input, therefore it can contain also the data of the following events, and if the event was generated by a large amount of text, not all of it may be available.

When called while an event handler is not active, the return value is None . xmlparser. ExternalEntityParserCreate ( context [ , encoding ] ) ¶ Create a “child” parser which can be used to parse an external parsed entity referred to by content parsed by the parent parser. The context parameter should be the string passed to the ExternalEntit

The rest of this page is on the live site.