gh-141004: document the Python version adding each PyExpat_CAPI member (GH-160471)

Author: picnixz

Doc/c-api/pyexpat.rst

@@ -6,7 +6,27 @@ Expat C API
 The :mod:`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 :file:`pyexpat.h`,
-which must be included after Expat's :file:`expat.h` header.
+which is not included by :file:`Python.h` and must be included after Expat's
+:file:`expat.h` header.
+
+To use the C API, add the following code to the extension module
+initialization 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)
+   )) {
+       PyErr_SetString(PyExc_ImportError, "pyexpat version is incompatible");
+       goto error;
+   }
 
 .. c:macro:: PyExpat_CAPSULE_NAME
 
@@ -20,7 +40,7 @@ which must be included after Expat's :file:`expat.h` header.
    The string identifying the layout of :c:struct:`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 :c:expr:`sizeof(struct PyExpat_CAPI)`.
+   and its ``size`` member is at least :c:expr:`sizeof(struct PyExpat_CAPI)`.
 
 
 .. c:struct:: PyExpat_CAPI
@@ -46,7 +66,8 @@ which must be included after Expat's :file:`expat.h` header.
                  int MICRO_VERSION
 
       Major, minor, and micro version numbers of the Expat library used by
-      :mod:`xml.parsers.expat`.
+      :mod:`xml.parsers.expat`, set to ``XML_MAJOR_VERSION``,
+      ``XML_MINOR_VERSION``, and ``XML_MICRO_VERSION`` respectively.
 
    .. c:member:: void (*SetUnknownEncodingHandler)(XML_Parser parser, XML_UnknownEncodingHandler handler, void *encodingHandlerData)
 
@@ -63,14 +84,15 @@ which must be included after Expat's :file:`expat.h` header.
       The *encodingHandlerData* argument is unused.
       Calling this handler requires an :term:`attached thread state`.
 
+      .. versionadded:: 3.3
+
    Pointers to the corresponding Expat functions, or ``NULL`` if not
    available in the Expat version used by :mod:`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
-   <https://libexpat.github.io/doc/api/latest/>`_ for their behavior
-   and the minimum Expat version they appear in.
+   <https://libexpat.github.io/doc/api/latest/>`_ for their behavior.
 
    .. c:member:: const XML_LChar *(*ErrorString)(enum XML_Error code)
                  enum XML_Error (*GetErrorCode)(XML_Parser parser)
@@ -86,14 +108,53 @@ which must be included after Expat's :file:`expat.h` header.
                  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 <https://libexpat.github.io/doc/api/latest/>`_.
+
+   .. c:member:: void (*SetStartDoctypeDeclHandler)(XML_Parser parser, XML_StartDoctypeDeclHandler start)
+
+      .. versionadded:: 3.2
+
+   .. c:member:: enum XML_Status (*SetEncoding)(XML_Parser parser, const XML_Char *encoding)
+
+      .. versionadded:: 3.3
+
+   .. c:member:: int (*SetHashSalt)(XML_Parser parser, unsigned long 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, unsigned long long activationThresholdBytes)
+
+      Might be ``NULL`` for Expat versions prior to 2.7.2.
+
+      .. versionadded:: 3.10
+
+   .. c:member:: XML_Bool (*SetAllocTrackerMaximumAmplification)(XML_Parser parser, float maxAmplificationFactor)
+
+      Might be ``NULL`` for Expat versions prior to 2.7.2.
+
+      .. versionadded:: 3.10
+
+   .. c:member:: XML_Bool (*SetBillionLaughsAttackProtectionActivationThreshold)(XML_Parser parser, unsigned long long activationThresholdBytes)
+
+      Might be ``NULL`` for Expat versions prior to 2.4.0.
+
+      .. versionadded:: 3.10
+
+   .. c:member:: XML_Bool (*SetBillionLaughsAttackProtectionMaximumAmplification)(XML_Parser parser, float maxAmplificationFactor)
+
+      Might be ``NULL`` for Expat versions prior to 2.4.0.
+
+      .. versionadded:: 3.10
+
+   .. c:member:: XML_Bool (*SetHashSalt16Bytes)(XML_Parser parser, const uint8_t entropy[16])
+
+      Might be ``NULL`` for Expat versions prior to 2.8.0.
+
+      .. versionadded:: 3.16