Skip to content

gh-141004: document the Python version adding each PyExpat_CAPI member #160471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
encukou merged 2 commits into from
Oct 23, 2026
+77 −16
Merged

gh-141004: document the Python version adding each PyExpat_CAPI member #160471

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d115d6
gh-141004: document versions and Expat requirements of the `pyexpat` …
picnixz Oct 23, 2026
a063ffe
Update Doc/c-api/pyexpat.rst
picnixz Oct 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 77 additions & 16 deletions Doc/c-api/pyexpat.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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)

Expand All @@ -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)
Expand All @@ -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.
Comment thread
picnixz marked this conversation as resolved.

.. 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
Loading