@@ -193,6 +193,71 @@ The CLI supports the following options:
193
193
The list of files to process.
194
194
195
195
196
+ .. _clinic-classes :
197
+
198
+ Classes for extending Argument Clinic
199
+ -------------------------------------
200
+
201
+ .. module :: clinic
202
+
203
+ .. class :: CConverter
204
+
205
+ The base class for all converters.
206
+ See :ref: `clinic-howto-custom-converter ` for how to subclass this class.
207
+
208
+ .. attribute :: type
209
+
210
+ The C type to use for this variable.
211
+ :attr: `!type ` should be a Python string specifying the type,
212
+ e.g. ``'int' ``.
213
+ If this is a pointer type, the type string should end with ``' *' ``.
214
+
215
+ .. attribute :: default
216
+
217
+ The Python default value for this parameter, as a Python value.
218
+ Or the magic value ``unspecified `` if there is no default.
219
+
220
+ .. attribute :: py_default
221
+
222
+ :attr: `!default ` as it should appear in Python code,
223
+ as a string.
224
+ Or ``None `` if there is no default.
225
+
226
+ .. attribute :: c_default
227
+
228
+ :attr: `!default ` as it should appear in C code,
229
+ as a string.
230
+ Or ``None `` if there is no default.
231
+
232
+ .. attribute :: c_ignored_default
233
+
234
+ The default value used to initialize the C variable when
235
+ there is no default, but not specifying a default may
236
+ result in an "uninitialized variable" warning. This can
237
+ easily happen when using option groups—although
238
+ properly written code will never actually use this value,
239
+ the variable does get passed in to the impl, and the
240
+ C compiler will complain about the "use" of the
241
+ uninitialized value. This value should always be a
242
+ non-empty string.
243
+
244
+ .. attribute :: converter
245
+
246
+ The name of the C converter function, as a string.
247
+
248
+ .. attribute :: impl_by_reference
249
+
250
+ A boolean value. If true,
251
+ Argument Clinic will add a ``& `` in front of the name of
252
+ the variable when passing it into the impl function.
253
+
254
+ .. attribute :: parse_by_reference
255
+
256
+ A boolean value. If true,
257
+ Argument Clinic will add a ``& `` in front of the name of
258
+ the variable when passing it into :c:func: `PyArg_ParseTuple `.
259
+
260
+
196
261
.. _clinic-tutorial :
197
262
198
263
Tutorial
@@ -1343,7 +1408,7 @@ See also :pep:`573`.
1343
1408
How to write a custom converter
1344
1409
-------------------------------
1345
1410
1346
- A converter is a Python class that inherits from :py:class: `! CConverter `.
1411
+ A converter is a Python class that inherits from :py:class: `CConverter `.
1347
1412
The main purpose of a custom converter, is for parameters parsed with
1348
1413
the ``O& `` format unit --- parsing such a parameter means calling
1349
1414
a :c:func: `PyArg_ParseTuple ` "converter function".
@@ -1355,73 +1420,13 @@ your converter class with the ``_converter`` suffix stripped off.
1355
1420
1356
1421
Instead of subclassing :py:meth: `!CConverter.__init__ `,
1357
1422
write a :py:meth: `!converter_init ` method.
1358
- Apart for the * self * parameter, all additional :py:meth: `!converter_init `
1359
- parameters **must ** be keyword-only.
1423
+ :py:meth: `!converter_init ` always accepts a * self * parameter.
1424
+ After * self *, all additional parameters **must ** be keyword-only.
1360
1425
Any arguments passed to the converter in Argument Clinic
1361
1426
will be passed along to your :py:meth: `!converter_init ` method.
1362
- See :py:class: `! CConverter ` for a list of members you may wish to specify in
1427
+ See :py:class: `CConverter ` for a list of members you may wish to specify in
1363
1428
your subclass.
1364
1429
1365
- .. module :: clinic
1366
-
1367
- .. class :: CConverter
1368
-
1369
- The base class for all converters.
1370
- See :ref: `clinic-howto-custom-converter ` for how to subclass this class.
1371
-
1372
- .. attribute :: type
1373
-
1374
- The C type to use for this variable.
1375
- :attr: `!type ` should be a Python string specifying the type,
1376
- e.g. ``'int' ``.
1377
- If this is a pointer type, the type string should end with ``' *' ``.
1378
-
1379
- .. attribute :: default
1380
-
1381
- The Python default value for this parameter, as a Python value.
1382
- Or the magic value ``unspecified `` if there is no default.
1383
-
1384
- .. attribute :: py_default
1385
-
1386
- :attr: `!default ` as it should appear in Python code,
1387
- as a string.
1388
- Or ``None `` if there is no default.
1389
-
1390
- .. attribute :: c_default
1391
-
1392
- :attr: `!default ` as it should appear in C code,
1393
- as a string.
1394
- Or ``None `` if there is no default.
1395
-
1396
- .. attribute :: c_ignored_default
1397
-
1398
- The default value used to initialize the C variable when
1399
- there is no default, but not specifying a default may
1400
- result in an "uninitialized variable" warning. This can
1401
- easily happen when using option groups—although
1402
- properly written code will never actually use this value,
1403
- the variable does get passed in to the impl, and the
1404
- C compiler will complain about the "use" of the
1405
- uninitialized value. This value should always be a
1406
- non-empty string.
1407
-
1408
- .. attribute :: converter
1409
-
1410
- The name of the C converter function, as a string.
1411
-
1412
- .. attribute :: impl_by_reference
1413
-
1414
- A boolean value. If true,
1415
- Argument Clinic will add a ``& `` in front of the name of
1416
- the variable when passing it into the impl function.
1417
-
1418
- .. attribute :: parse_by_reference
1419
-
1420
- A boolean value. If true,
1421
- Argument Clinic will add a ``& `` in front of the name of
1422
- the variable when passing it into :c:func: `PyArg_ParseTuple `.
1423
-
1424
-
1425
1430
Here's the simplest example of a custom converter, from :source: `Modules/zlibmodule.c `::
1426
1431
1427
1432
/*[python input]
0 commit comments