Expat C API

The xml.parsers.expat module exposes selected Expat functions through its expat_CAPI capsule. This allows extension modules to use the same Expat library as Python. The interface is declared in pyexpat.h, which must be included after Expat’s expat.h header.

PyExpat_CAPSULE_NAME

The name of the capsule containing the Expat C API: "pyexpat.expat_CAPI". Pass this to PyCapsule_Import() to obtain a pointer to a PyExpat_CAPI.

PyExpat_CAPI_MAGIC

The string identifying the layout of PyExpat_CAPI. Before using the function pointers in the structure, check that its magic member compares equal to this string using strcmp(), its size member is at least sizeof(struct PyExpat_CAPI), and its PyExpat_CAPI.MAJOR_VERSION, PyExpat_CAPI.MINOR_VERSION, and PyExpat_CAPI.MICRO_VERSION members equal the XML_MAJOR_VERSION, XML_MINOR_VERSION, and XML_MICRO_VERSION macros, respectively, from the expat.h header used to build the extension.

struct PyExpat_CAPI

Table of function pointers exported by xml.parsers.expat. The capsule owns this structure: treat it as read-only and do not free it. Keep a strong reference to the capsule while using the table.

Check the compatibility fields as described under PyExpat_CAPI_MAGIC before using the function pointers.

char *magic

Interface identifier, set to PyExpat_CAPI_MAGIC.

int size

Size of the structure in bytes, set to sizeof(struct PyExpat_CAPI) by the xml.parsers.expat module that created the capsule.

int MAJOR_VERSION

int MINOR_VERSION

int MICRO_VERSION

Major, minor, and micro version numbers of the Expat library used by xml.parsers.expat.

void (*SetUnknownEncodingHandler)(XML_Parser parser, XML_UnknownEncodingHandler handler, void *encodingHandlerData)

Pointer to XML_SetUnknownEncodingHandler. The handler may set a Python exception on failure. The caller must check for a Python exception after parsing.

int (*DefaultUnknownEncodingHandler)(void *encodingHandlerData, const XML_Char *name, XML_Encoding *info)

Python’s unknown-encoding handler for Expat, used with XML_SetUnknownEncodingHandler. It uses Python’s codec registry to fill info. The encodingHandlerData argument is unused. Calling this handler requires an attached thread state.

Pointers to the corresponding Expat functions, or NULL if not available in the Expat version used by xml.parsers.expat, are listed below.

Member names omit the XML_ prefix; for example, SetHashSalt exposes Expat’s XML_SetHashSalt function. See the Expat API reference for their behavior and the minimum Expat version they appear in.

const XML_LChar *(*ErrorString)(enum XML_Error code)

enum XML_Error (*GetErrorCode)(XML_Parser parser)

XML_Size (*GetErrorColumnNumber)(XML_Parser parser)

XML_Size (*GetErrorLineNumber)(XML_Parser parser)

enum XML_Status (*Parse)(XML_Parser parser, const char *s, int len, int isFinal)

XML_Parser (*ParserCreate_MM)(const XML_Char *encoding, const XML_Memory_Handling_Suite *memsuite, const XML_Char *namespaceSeparator)

void (*ParserFree)(XML_Parser parser)

void (*SetCharacterDataHandler)(XML_Parser parser, XML_CharacterDataHandler handler)

void (*SetCommentHandler)(XML_Parser parser, XML_CommentHandler handler)

void (*SetDefaultHandlerExpand)(XML_Parser parser, XML_DefaultHandler handler)

void (*SetElementHandler)(XML_Parser parser, XML_StartElementHandler start, XML_EndElementHandler end)

void (*SetNamespaceDeclHandler)(XML_Parser parser, XML_StartNamespaceDeclHandler start, XML_EndNamespaceDeclHandler end)

void (*SetProcessingInstructionHandler)(XML_Parser parser, XML_ProcessingInstructionHandler handler)

void (*SetUserData)(XML_Parser parser, void *userData)

void (*SetStartDoctypeDeclHandler)(XML_Parser parser, XML_StartDoctypeDeclHandler start)

enum XML_Status (*SetEncoding)(XML_Parser parser, const XML_Char *encoding)

int (*SetHashSalt)(XML_Parser parser, unsigned long hash_salt)

XML_Bool (*SetReparseDeferralEnabled)(XML_Parser parser, XML_Bool enabled)

XML_Bool (*SetAllocTrackerActivationThreshold)(XML_Parser parser, unsigned long long activationThresholdBytes)

XML_Bool (*SetAllocTrackerMaximumAmplification)(XML_Parser parser, float maxAmplificationFactor)

XML_Bool (*SetBillionLaughsAttackProtectionActivationThreshold)(XML_Parser parser, unsigned long long activationThresholdBytes)

XML_Bool (*SetBillionLaughsAttackProtectionMaximumAmplification)(XML_Parser parser, float maxAmplificationFactor)

XML_Bool (*SetHashSalt16Bytes)(XML_Parser parser, const uint8_t entropy[16])

See the Expat API reference.