API C do Expat

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

O nome da cápsula que contém a API C Expat: "pyexpat.expat_CAPI". Passe isso para PyCapsule_Import() para obter um ponteiro para um 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

Tabela de ponteiros de função exportada por xml.parsers.expat. A cápsula detém esta estrutura: trate-a como somente leitura e não a libere. Mantenha uma referência forte à cápsula enquanto estiver utilizando a tabela.

Verifique os campos de compatibilidade, conforme descrito em PyExpat_CAPI_MAGIC, antes de utilizar os ponteiros de função.

char *magic

Identificador da interface, define para PyExpat_CAPI_MAGIC.

int size

Tamanho da estrutura em bytes, definido como sizeof(struct PyExpat_CAPI) pelo módulo xml.parsers.expat que criou a cápsula.

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)

Ponteiro para XML_SetUnknownEncodingHandler. O manipulador pode definir uma exceção Python em caso de falha. O chamador deve verificar se ocorreu uma exceção Python após a análise.

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

Manipulador de codificação desconhecida do Python para o Expat, utilizado com XML_SetUnknownEncodingHandler. Ele emprega o registro de codecs do Python para preencher info. O argumento encodingHandlerData não é utilizado. A chamada deste manipulador requer um estado de thread anexado.

Adicionado na versão 3.3.

Abaixo, estão listados os ponteiros para as funções correspondentes da Expat ou NULL, caso não estejam disponíveis na versão da Expat utilizada pelo xml.parsers.expat.

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)

Adicionado na versão 3.2.

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

Adicionado na versão 3.3.

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

Might be NULL for Expat versions prior to 2.1.0.

Adicionado na versão 3.4.

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

Might be NULL for Expat versions prior to 2.6.0.

Adicionado na versão 3.8.

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

Might be NULL for Expat versions prior to 2.7.2.

Adicionado na versão 3.10.

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

Might be NULL for Expat versions prior to 2.7.2.

Adicionado na versão 3.10.

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

Might be NULL for Expat versions prior to 2.4.0.

Adicionado na versão 3.10.

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

Might be NULL for Expat versions prior to 2.4.0.

Adicionado na versão 3.10.

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

Might be NULL for Expat versions prior to 2.8.0.

Adicionado na versão 3.16.