Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit6164db5

Browse files
committed
document Expat C API
1 parent87942d9 commit6164db5

File tree

2 files changed

+211
-1
lines changed

2 files changed

+211
-1
lines changed

‎Doc/c-api/concrete.rst‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,5 +115,13 @@ Other Objects
115115
gen.rst
116116
coro.rst
117117
contextvars.rst
118-
datetime.rst
119118
typehints.rst
119+
120+
121+
C API for extension modules
122+
===========================
123+
124+
..toctree::
125+
126+
datetime.rst
127+
expat.rst

‎Doc/c-api/expat.rst‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
..highlight::c
2+
3+
Expat C API
4+
-----------
5+
6+
:mod:`pyexpat` exposes a C interface for extension modules.
7+
Consumers must include the header file:file:`pyexpat.h` (which is not
8+
included by default by:file:`Python.h`) and ``expat.h`` for Expat.
9+
10+
To use the C API, consider adding the following code in your extension
11+
module initilisation function:
12+
13+
..code-block::
14+
15+
...
16+
17+
PyObject *capsule = PyImport_ImportModuleAttrString("pyexpat", "expat_CAPI"));
18+
if (capsule == NULL) { goto error; }
19+
struct PyExpat_CAPI *capi = PyCapsule_GetPointer(capsule, PyExpat_CAPSULE_NAME));
20+
if (capi == NULL) { goto error; }
21+
22+
/* check if the C API is compatible with the version of Expat version */
23+
if (strcmp(capi->magic, PyExpat_CAPI_MAGIC) != 0
24+
|| (size_t)capi->size < sizeof(struct PyExpat_CAPI)
25+
|| capi->MAJOR_VERSION != XML_MAJOR_VERSION
26+
|| capi->MINOR_VERSION != XML_MINOR_VERSION
27+
|| capi->MICRO_VERSION != XML_MICRO_VERSION
28+
) {
29+
PyErr_SetString(PyExc_ImportError, "pyexpat version is incompatible");
30+
goto error;
31+
}
32+
33+
/* store 'capsule' and 'capi' in the module state */
34+
...
35+
36+
37+
..c:macro:: PyExpat_CAPI_MAGIC
38+
39+
The Expat C API magic number.
40+
41+
42+
..c:macro:: PyExpat_CAPSULE_NAME
43+
44+
The Expat C API capsule name to import.
45+
46+
Import first a *capsule* object from:mod:`pyexpat`
47+
via ``PyImport_ImportModuleAttrString("pyexpat", "expat_CAPI"));``
48+
and get the corresponding:c:type:`PyExpat_CAPI` object using
49+
``PyCapsule_GetPointer(capsule, PyExpat_CAPSULE_NAME)``.
50+
51+
52+
..c:struct:: PyExpat_CAPI
53+
54+
The Expat C API structure.
55+
56+
.. below are members that were added in Python 2.x
57+
58+
..c:member::char *magic
59+
60+
Set to:c:macro:`PyExpat_CAPI_MAGIC`.
61+
62+
..c:member::int size
63+
64+
Set to ``sizeof(struct PyExpat_CAPI)``.
65+
66+
..c:member:: MAJOR_VERSION
67+
MINOR_VERSION
68+
MICRO_VERSION
69+
70+
Set to ``XML_MAJOR_VERSION``, ``XML_MINOR_VERSION``,
71+
and ``XML_MICRO_VERSION`` respectively of the linked
72+
Expat library.
73+
74+
The following members expose the C API as provided by Expat.
75+
See the `official documentation<https://libexpat.github.io/doc/api/latest>`_
76+
for details (some names may slightly differ but the signature and intent
77+
will not).
78+
79+
..c:member::const XML_LChar *(*ErrorString)(enum XML_Error errno)
80+
..c:member::enumXML_Error (*GetErrorCode)(XML_Parser parser)
81+
82+
..c:member:: XML_Size (*GetErrorColumnNumber)(XML_Parser parser)
83+
..c:member:: XML_Size (*GetErrorLineNumber)(XML_Parser parser)
84+
85+
..c:member::enumXML_Status (*Parse)(\
86+
XML_Parser parser,\
87+
const char *s, int len, int isFinal)
88+
89+
..c:member:: XML_Parser (*ParserCreate_MM)(\
90+
const XML_Char *encoding,\
91+
const XML_Memory_Handling_Suite *memsuite,\
92+
const XML_Char *sep)
93+
94+
..c:member::void (*ParserFree)(XML_Parser parser)
95+
96+
..c:member::void (*SetCharacterDataHandler)(\
97+
XML_Parser parser,\
98+
XML_CharacterDataHandler handler)
99+
100+
..c:member::void (*SetCommentHandler)(\
101+
XML_Parser parser,\
102+
XML_CommentHandler handler)
103+
104+
..c:member::void (*SetDefaultHandlerExpand)(\
105+
XML_Parser parser,\
106+
XML_DefaultHandler handler)
107+
108+
..c:member::void (*SetElementHandler)(\
109+
XML_Parser parser,\
110+
XML_StartElementHandler start,\
111+
XML_EndElementHandler end)
112+
113+
..c:member::void (*SetNamespaceDeclHandler)(\
114+
XML_Parser parser,\
115+
XML_StartNamespaceDeclHandler start,\
116+
XML_EndNamespaceDeclHandler end)
117+
118+
..c:member::void (*SetProcessingInstructionHandler)(\
119+
XML_Parser parser,\
120+
XML_ProcessingInstructionHandler handler)
121+
122+
..c:member::void (*SetUnknownEncodingHandler)(\
123+
XML_Parser parser,\
124+
XML_UnknownEncodingHandler handler,\
125+
void *encodingHandlerData)
126+
127+
..c:member::void (*SetUserData)(\
128+
XML_Parser parser,\
129+
void *userData)
130+
131+
.. below are members that were added after Python 3.0
132+
133+
..c:member::void (*SetStartDoctypeDeclHandler)(\
134+
XML_Parser parser,\
135+
XML_StartDoctypeDeclHandler start)
136+
137+
..versionadded::3.2
138+
139+
..c:member::enumXML_Status (*SetEncoding)(\
140+
XML_Parser parser,\
141+
const XML_Char *encoding)
142+
143+
..versionadded::3.3
144+
145+
..c:member::int (*DefaultUnknownEncodingHandler)(\
146+
void *encodingHandlerData,\
147+
const XML_Char *name,\
148+
XML_Encoding *info)
149+
150+
..versionadded::3.3
151+
152+
..c:member::int (*SetHashSalt)(\
153+
XML_Parser parser,\
154+
unsignedlong hash_salt)
155+
156+
Might be NULL for Expat versions prior to 2.1.0.
157+
158+
..versionadded::3.4
159+
160+
..c:member:: XML_Bool (*SetReparseDeferralEnabled)(\
161+
XML_Parser parser,\
162+
XML_Bool enabled)
163+
164+
Might be NULL for Expat versions prior to 2.6.0.
165+
166+
..versionadded::3.8
167+
168+
..c:member:: XML_Bool (*SetAllocTrackerActivationThreshold)(\
169+
XML_Parser parser,\
170+
unsignedlonglong activationThresholdBytes)
171+
172+
Might be NULL for Expat versions prior to 2.7.2.
173+
174+
.. uncomment this when the backport is done
175+
..versionadded::3.10
176+
177+
..c:member:: XML_Bool (*SetAllocTrackerMaximumAmplification)(\
178+
XML_Parser parser,\
179+
float maxAmplificationFactor)
180+
181+
Might be NULL for Expat versions prior to 2.7.2.
182+
183+
.. uncomment this when the backport is done
184+
..versionadded::3.10
185+
186+
..c:member:: XML_Bool (*SetBillionLaughsAttackProtectionActivationThreshold)(\
187+
XML_Parser parser,\
188+
unsignedlonglong activationThresholdBytes)
189+
190+
Might be NULL for Expat versions prior to 2.4.0.
191+
192+
.. uncomment this when the backport is done
193+
..versionadded::3.10
194+
195+
..c:member:: XML_Bool (*SetBillionLaughsAttackProtectionMaximumAmplification)(\
196+
XML_Parser parser,\
197+
float maxAmplificationFactor)
198+
199+
Might be NULL for Expat versions prior to 2.4.0.
200+
201+
.. uncomment this when the backport is done
202+
..versionadded::3.10

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp