gh-141004: document pyexpat C API

Doc/c-api/concrete.rst

@@ -125,3 +125,4 @@ C API for extension modules
 
  curses.rst
  datetime.rst
+ expat.rst

Doc/c-api/expat.rst

@@ -0,0 +1,193 @@
+.. highlight:: c
+
+Expat C API
+-----------
+
+:mod:`!pyexpat` exposes a C interface for extension modules.
+Consumers must include the header file :file:`pyexpat.h` (which is not
+included by default by :file:`Python.h`) and ``expat.h`` for Expat.
+
+To use the C API, consider adding the following code in your extension
+module initilisation function and store the pointer to the C API in
+the module state:
+
+.. code-block::
+
+ struct PyExpat_CAPI *capi = NULL;
+ capi = (struct PyExpat_CAPI *)PyCapsule_Import(PyExpat_CAPSULE_NAME, 0);
+ if (capi == NULL){
+ goto error;
+ }
+ if (!(
+ strcmp(capi->magic, PyExpat_CAPI_MAGIC) == 0
+ && (size_t)capi->size >= sizeof(struct PyExpat_CAPI)
+ && capi->MAJOR_VERSION == XML_MAJOR_VERSION
+ && capi->MINOR_VERSION == XML_MINOR_VERSION
+ && capi->MICRO_VERSION == XML_MICRO_VERSION
+ )){
+ PyErr_SetString(PyExc_ImportError, "pyexpat version is incompatible");
+ goto error;
+ }
+
+
+.. c:macro:: PyExpat_CAPI_MAGIC
+
+ The Expat C API magic number.
+
+
+.. c:macro:: PyExpat_CAPSULE_NAME
+
+ The Expat C API capsule name to import via :c:func:`PyCapsule_Import`.
+
+
+.. c:struct:: PyExpat_CAPI
+
+ The Expat C API structure.
+
+.. below are members that were added in Python 2.x
+
+ .. c:member::char *magic
+
+ Set to :c:macro:`PyExpat_CAPI_MAGIC`.
+
+ .. c:member::int size
+
+ Set to ``sizeof(struct PyExpat_CAPI)``.
+
+ .. c:member::int MAJOR_VERSION
+int MINOR_VERSION
+int MICRO_VERSION
+
+ Set to ``XML_MAJOR_VERSION``, ``XML_MINOR_VERSION``,
+ and ``XML_MICRO_VERSION`` respectively of the linked
+ Expat library.
+
+ The following members expose the C API as provided by Expat.
+ See the `official documentation <https://libexpat.github.io/doc/api/latest>`_
+ for details (some names may slightly differ but the signature and intent
+ will not).
+
+ .. c:member::const XML_LChar *(*ErrorString)(enum XML_Error errno)
+ .. c:member::enumXML_Error (*GetErrorCode)(XML_Parser parser)
+
+ .. c:member:: XML_Size (*GetErrorColumnNumber)(XML_Parser parser)
+ .. c:member:: XML_Size (*GetErrorLineNumber)(XML_Parser parser)
+
+ .. c:member::enumXML_Status (*Parse)(\
+ XML_Parser parser,\
+ const char *s, int len, int isFinal)
+
+ .. c:member:: XML_Parser (*ParserCreate_MM)(\
+const XML_Char *encoding,\
+const XML_Memory_Handling_Suite *memsuite,\
+const XML_Char *sep)
+
+ .. c:member::void (*ParserFree)(XML_Parser parser)
+
+ .. c:member::void (*SetCharacterDataHandler)(\
+ XML_Parser parser,\
+ XML_CharacterDataHandler handler)
+
+ .. c:member::void (*SetCommentHandler)(\
+ XML_Parser parser,\
+ XML_CommentHandler handler)
+
+ .. c:member::void (*SetDefaultHandlerExpand)(\
+ XML_Parser parser,\
+ XML_DefaultHandler handler)
+
+ .. c:member::void (*SetElementHandler)(\
+ XML_Parser parser,\
+ XML_StartElementHandler start,\
+ XML_EndElementHandler end)
+
+ .. c:member::void (*SetNamespaceDeclHandler)(\
+ XML_Parser parser,\
+ XML_StartNamespaceDeclHandler start,\
+ XML_EndNamespaceDeclHandler end)
+
+ .. c:member::void (*SetProcessingInstructionHandler)(\
+ XML_Parser parser,\
+ XML_ProcessingInstructionHandler handler)
+
+ .. c:member::void (*SetUnknownEncodingHandler)(\
+ XML_Parser parser,\
+ XML_UnknownEncodingHandler handler,\
+void *encodingHandlerData)
+
+ .. c:member::void (*SetUserData)(\
+ XML_Parser parser,\
+void *userData)
+
+.. below are members that were added after Python 3.0
+
+ .. c:member::void (*SetStartDoctypeDeclHandler)(\
+ XML_Parser parser,\
+ XML_StartDoctypeDeclHandler start)
+
+ .. versionadded:: 3.2
+
+ .. c:member::enumXML_Status (*SetEncoding)(\
+ XML_Parser parser,\
+ const XML_Char *encoding)
+
+ .. versionadded:: 3.3
+
+ .. c:member::int (*DefaultUnknownEncodingHandler)(\
+void *encodingHandlerData,\
+const XML_Char *name,\
+ XML_Encoding *info)
+
+ .. versionadded:: 3.3
+
+ .. c:member::int (*SetHashSalt)(\
+ XML_Parser parser,\
+unsignedlong hash_salt)
+
+ Might be ``NULL`` for Expat versions prior to 2.1.0.
+
+ .. versionadded:: 3.4
+
+ .. c:member:: XML_Bool (*SetReparseDeferralEnabled)(\
+ XML_Parser parser,\
+ XML_Bool enabled)
+
+ Might be ``NULL`` for Expat versions prior to 2.6.0.
+
+ .. versionadded:: 3.8
+
+ .. c:member:: XML_Bool (*SetAllocTrackerActivationThreshold)(\
+ XML_Parser parser,\
+unsignedlonglong activationThresholdBytes)
+
+ Might be ``NULL`` for Expat versions prior to 2.7.2.
+
+.. uncomment this when the backport is done
+ .. versionadded:: 3.10
+
+ .. c:member:: XML_Bool (*SetAllocTrackerMaximumAmplification)(\
+ XML_Parser parser,\
+float maxAmplificationFactor)
+
+ Might be ``NULL`` for Expat versions prior to 2.7.2.
+
+.. uncomment this when the backport is done
+ .. versionadded:: 3.10
+
+ .. c:member:: XML_Bool (*SetBillionLaughsAttackProtectionActivationThreshold)(\
+ XML_Parser parser,\
+unsignedlonglong activationThresholdBytes)
+
+ Might be ``NULL`` for Expat versions prior to 2.4.0.
+
+.. uncomment this when the backport is done
+ .. versionadded:: 3.10
+
+ .. c:member:: XML_Bool (*SetBillionLaughsAttackProtectionMaximumAmplification)(\
+ XML_Parser parser,\
+float maxAmplificationFactor)
+
+ Might be ``NULL`` for Expat versions prior to 2.4.0.
+
+.. uncomment this when the backport is done
+ .. versionadded:: 3.10

Doc/conf.py

@@ -223,6 +223,30 @@
  ('envvar', 'USERPROFILE'),
 ]
 
+# Vendored identifiers without intersphinx support.
+nitpick_ignore += [
+ # used in c-api/expat.rst
+ ('c:identifier', 'XML_Bool'),
+ ('c:identifier', 'XML_Char'),
+ ('c:identifier', 'XML_CharacterDataHandler'),
+ ('c:identifier', 'XML_CommentHandler'),
+ ('c:identifier', 'XML_DefaultHandler'),
+ ('c:identifier', 'XML_Encoding'),
+ ('c:identifier', 'XML_EndElementHandler'),
+ ('c:identifier', 'XML_EndNamespaceDeclHandler'),
+ ('c:identifier', 'XML_Error'),
+ ('c:identifier', 'XML_LChar'),
+ ('c:identifier', 'XML_Memory_Handling_Suite'),
+ ('c:identifier', 'XML_Parser'),
+ ('c:identifier', 'XML_ProcessingInstructionHandler'),
+ ('c:identifier', 'XML_Size'),
+ ('c:identifier', 'XML_StartDoctypeDeclHandler'),
+ ('c:identifier', 'XML_StartElementHandler'),
+ ('c:identifier', 'XML_StartNamespaceDeclHandler'),
+ ('c:identifier', 'XML_Status'),
+ ('c:identifier', 'XML_UnknownEncodingHandler'),
+]
+
 # Temporary undocumented names.
 # In future this list must be empty.
 nitpick_ignore += [

Include/pyexpat.h

@@ -6,9 +6,8 @@
 #define PyExpat_CAPI_MAGIC "pyexpat.expat_CAPI 1.1"
 #define PyExpat_CAPSULE_NAME "pyexpat.expat_CAPI"
 
-struct PyExpat_CAPI
-{
- char* magic; /* set to PyExpat_CAPI_MAGIC */
+struct PyExpat_CAPI{
+ char *magic; /* set to PyExpat_CAPI_MAGIC */
  int size; /* set to sizeof(struct PyExpat_CAPI) */
  int MAJOR_VERSION;
  int MINOR_VERSION;
@@ -64,4 +63,3 @@ struct PyExpat_CAPI
  XML_Parser parser, float maxAmplificationFactor);
  /* always add new stuff to the end! */
 };
-