|
1 | 1 | .. highlight:: c
|
2 | 2 |
|
3 |
| -.. _howto-clinic: |
| 3 | +.. _clinic: |
4 | 4 |
|
5 |
| -********************** |
6 |
| -Argument Clinic How-To |
7 |
| -********************** |
| 5 | +*************** |
| 6 | +Argument Clinic |
| 7 | +*************** |
8 | 8 |
|
9 | 9 | :author: Larry Hastings
|
10 | 10 |
|
11 |
| -**Source code:** :source:`Tools/clinic/clinic.py`. |
| 11 | +**Source code:** :cpy-file:`Tools/clinic/clinic.py`. |
12 | 12 |
|
13 |
| -.. topic:: Abstract |
| 13 | +Argument Clinic is a preprocessor for CPython C files. |
| 14 | +It was introduced in Python 3.4 with :pep:`436`, |
| 15 | +in order to provide introspection signatures, |
| 16 | +and to generate performant and tailor-made boilerplate code |
| 17 | +for argument parsing in CPython builtins, module level functions, and class methods. |
| 18 | +This document is divided in four major sections: |
14 | 19 |
|
15 |
| - Argument Clinic is a preprocessor for CPython C files. |
16 |
| - It was introduced in Python 3.4 with :pep:`436`, |
17 |
| - in order to provide introspection signatures, |
18 |
| - and to generate performant and tailor-made boilerplate code |
19 |
| - for argument parsing in CPython builtins, |
20 |
| - module level functions, and class methods. |
21 |
| - This document is divided in four major sections: |
22 |
| - |
23 |
| - * :ref:`clinic-background` talks about the basic concepts and goals of |
24 |
| - Argument Clinic. |
25 |
| - * :ref:`clinic-reference` describes the command-line interface and Argument |
26 |
| - Clinic terminology. |
27 |
| - * :ref:`clinic-tutorial` guides you through all the steps required to |
28 |
| - adapt an existing C function to Argument Clinic. |
29 |
| - * :ref:`clinic-howtos` details how to handle specific tasks. |
| 20 | +* :ref:`clinic-background` talks about the basic concepts and goals of Argument Clinic. |
| 21 | +* :ref:`clinic-reference` describes the command-line interface and Argument Clinic terminology. |
| 22 | +* :ref:`clinic-tutorial` guides you through all the steps required to adapt an existing C function to Argument Clinic. |
| 23 | +* :ref:`clinic-howtos` details how to handle specific tasks. |
30 | 24 |
|
31 | 25 |
|
32 | 26 | .. note::
|
@@ -749,7 +743,7 @@ While functions using this approach can often be converted to
|
749 | 743 | use :c:func:`!PyArg_ParseTupleAndKeywords`, optional arguments, and default values,
|
750 | 744 | it's not always possible. Some of these legacy functions have
|
751 | 745 | behaviors :c:func:`!PyArg_ParseTupleAndKeywords` doesn't directly support.
|
752 |
| -The most obvious example is the builtin function :py:func:`range`, which has |
| 746 | +The most obvious example is the builtin function :py:func:`!range`, which has |
753 | 747 | an optional argument on the *left* side of its required argument!
|
754 | 748 | Another example is :py:meth:`curses.window.addch`, which has a group of two
|
755 | 749 | arguments that must always be specified together. (The arguments are
|
@@ -1358,7 +1352,7 @@ module level state. Use :c:func:`PyType_FromModuleAndSpec` to associate a new
|
1358 | 1352 | heap type with a module. You can now use :c:func:`PyType_GetModuleState` on
|
1359 | 1353 | the defining class to fetch the module state, for example from a module method.
|
1360 | 1354 |
|
1361 |
| -Example from :source:`Modules/zlibmodule.c`. |
| 1355 | +Example from :cpy-file:`Modules/zlibmodule.c`. |
1362 | 1356 | First, ``defining_class`` is added to the clinic input::
|
1363 | 1357 |
|
1364 | 1358 | /*[clinic input]
|
@@ -1399,7 +1393,7 @@ It is not possible to use ``defining_class`` with slot methods. In order to
|
1399 | 1393 | fetch the module state from such methods, use :c:func:`PyType_GetModuleByDef`
|
1400 | 1394 | to look up the module and then :c:func:`PyModule_GetState` to fetch the module
|
1401 | 1395 | state. Example from the ``setattro`` slot method in
|
1402 |
| -:source:`Modules/_threadmodule.c`:: |
| 1396 | +:cpy-file:`Modules/_threadmodule.c`:: |
1403 | 1397 |
|
1404 | 1398 | static int
|
1405 | 1399 | local_setattro(localobject *self, PyObject *name, PyObject *v)
|
@@ -1437,7 +1431,7 @@ will be passed along to your :py:meth:`!converter_init` method.
|
1437 | 1431 | See :py:class:`CConverter` for a list of members you may wish to specify in
|
1438 | 1432 | your subclass.
|
1439 | 1433 |
|
1440 |
| -Here's the simplest example of a custom converter, from :source:`Modules/zlibmodule.c`:: |
| 1434 | +Here's the simplest example of a custom converter, from :cpy-file:`Modules/zlibmodule.c`:: |
1441 | 1435 |
|
1442 | 1436 | /*[python input]
|
1443 | 1437 |
|
@@ -1470,7 +1464,7 @@ converters are themselves much simpler.
|
1470 | 1464 | Return converters must subclass :py:class:`!CReturnConverter`.
|
1471 | 1465 | There are no examples yet of custom return converters,
|
1472 | 1466 | because they are not widely used yet. If you wish to
|
1473 |
| -write your own return converter, please read :source:`Tools/clinic/clinic.py`, |
| 1467 | +write your own return converter, please read :cpy-file:`Tools/clinic/clinic.py`, |
1474 | 1468 | specifically the implementation of :py:class:`!CReturnConverter` and
|
1475 | 1469 | all its subclasses.
|
1476 | 1470 |
|
@@ -1917,7 +1911,7 @@ The ``@text_signature`` directive takes one argument:
|
1917 | 1911 | the custom signature as a string.
|
1918 | 1912 | The provided signature is copied verbatim to the generated docstring.
|
1919 | 1913 |
|
1920 |
| -Example from :source:`Objects/codeobject.c`:: |
| 1914 | +Example from :cpy-file:`Objects/codeobject.c`:: |
1921 | 1915 |
|
1922 | 1916 | /*[clinic input]
|
1923 | 1917 | @text_signature "($self, /, **changes)"
|
|
0 commit comments