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 is not included by Python.h and must be included after Expat's 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:

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;
}

PyExpat_CAPSULE_NAME

Expat C API を格納するカプセルの名前 "pyexpat.expat_CAPI"。 これを PyCapsule_Import() に渡すと、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

xml.parsers.expat がエクスポートする関数ポインタのテーブル。 この構造体はカプセルが所有しています。 読み取り専用として扱い、解放しないでください。 テーブルの使用中は、カプセルへの強参照を保持してください。

関数ポインタを使う前に、PyExpat_CAPI_MAGIC の説明に従って互換性を示すフィールドを確認してください。

char *magic

インターフェースの識別子。 PyExpat_CAPI_MAGIC に設定されます。

int size

構造体のサイズ (バイト単位)。 カプセルを作成した xml.parsers.expat モジュールによって sizeof(struct PyExpat_CAPI) に設定されます。

int MAJOR_VERSION

int MINOR_VERSION

int MICRO_VERSION

Major, minor, and micro version numbers of the Expat library used by xml.parsers.expat, set to XML_MAJOR_VERSION, XML_MINOR_VERSION, and XML_MICRO_VERSION respectively.

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

XML_SetUnknownEncodingHandler へのポインタ。 ハンドラは失敗時に Python の例外を設定する場合があります。 呼び出し側は解析後に Python の例外の有無を確認する必要があります。

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

XML_SetUnknownEncodingHandler で使う、Expat の未知のエンコーディングに対応する Python のハンドラ。 Python のコーデックレジストリを使って info に値を設定します。 encodingHandlerData 引数は使いません。 このハンドラを呼び出すには スレッド状態がアタッチされている 必要があります。

Added in version 3.3.

以下は、対応する Expat 関数へのポインタです。 xml.parsers.expat が使う Expat のバージョンで利用できない場合は NULL です。

Member names omit the XML_ prefix; for example, SetHashSalt exposes Expat's XML_SetHashSalt function. See the Expat API reference for their behavior.

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)

Added in version 3.2.

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

Added in version 3.3.

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

Might be NULL for Expat versions prior to 2.1.0.

Added in version 3.4.

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

Might be NULL for Expat versions prior to 2.6.0.

Added in version 3.8.

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

Might be NULL for Expat versions prior to 2.7.2.

Added in version 3.10.

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

Might be NULL for Expat versions prior to 2.7.2.

Added in version 3.10.

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

Might be NULL for Expat versions prior to 2.4.0.

Added in version 3.10.

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

Might be NULL for Expat versions prior to 2.4.0.

Added in version 3.10.

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

Might be NULL for Expat versions prior to 2.8.0.

Added in version 3.16.