Skip to content

Commit d58c74c

Browse files
[3.11] Docs: Argument Clinic: Move the CConverter class to the reference (GH-107671) (#107702)
(cherry picked from commit a6675b1) Co-authored-by: Erlend E. Aasland <erlend@python.org>
1 parent 1878419 commit d58c74c

File tree

1 file changed

+69
-64
lines changed

1 file changed

+69
-64
lines changed

Doc/howto/clinic.rst

+69-64
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,71 @@ The CLI supports the following options:
193193
The list of files to process.
194194

195195

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+
196261
.. _clinic-tutorial:
197262

198263
Tutorial
@@ -1343,7 +1408,7 @@ See also :pep:`573`.
13431408
How to write a custom converter
13441409
-------------------------------
13451410

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`.
13471412
The main purpose of a custom converter, is for parameters parsed with
13481413
the ``O&`` format unit --- parsing such a parameter means calling
13491414
a :c:func:`PyArg_ParseTuple` "converter function".
@@ -1355,73 +1420,13 @@ your converter class with the ``_converter`` suffix stripped off.
13551420

13561421
Instead of subclassing :py:meth:`!CConverter.__init__`,
13571422
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.
13601425
Any arguments passed to the converter in Argument Clinic
13611426
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
13631428
your subclass.
13641429

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-
14251430
Here's the simplest example of a custom converter, from :source:`Modules/zlibmodule.c`::
14261431

14271432
/*[python input]

0 commit comments

Comments
 (0)