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()" and  its
   "size" member is at least sizeof(struct PyExpat_CAPI).

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.
