@@ -27,7 +27,8 @@ Argument Clinic How-To
2727 version of Argument Clinic that ships with the next version
2828 of CPython *could * be totally incompatible and break all your code.
2929
30- The Goals Of Argument Clinic
30+
31+ The goals of Argument Clinic
3132============================
3233
3334Argument Clinic's primary goal
@@ -78,7 +79,7 @@ and it should be able to do many interesting and smart
7879things with all the information you give it.
7980
8081
81- Basic Concepts And Usage
82+ Basic concepts and usage
8283========================
8384
8485Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py ``.
@@ -141,7 +142,7 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic:
141142 a block.)
142143
143144
144- Converting Your First Function
145+ Converting your first function
145146==============================
146147
147148The best way to get a sense of how Argument Clinic works is to
@@ -550,7 +551,8 @@ Let's dive in!
550551
551552 Congratulations, you've ported your first function to work with Argument Clinic!
552553
553- Advanced Topics
554+
555+ Advanced topics
554556===============
555557
556558Now that you've had some experience working with Argument Clinic, it's time
@@ -628,7 +630,8 @@ after the last argument).
628630Currently the generated code will use :c:func: `PyArg_ParseTuple `, but this
629631will change soon.
630632
631- Optional Groups
633+
634+ Optional groups
632635---------------
633636
634637Some legacy functions have a tricky approach to parsing their arguments:
@@ -888,6 +891,7 @@ available. For each converter it'll show you all the parameters
888891it accepts, along with the default value for each parameter.
889892Just run ``Tools/clinic/clinic.py --converters `` to see the full list.
890893
894+
891895Py_buffer
892896---------
893897
@@ -897,7 +901,6 @@ you *must* not call :c:func:`PyBuffer_Release` on the provided buffer.
897901Argument Clinic generates code that does it for you (in the parsing function).
898902
899903
900-
901904Advanced converters
902905-------------------
903906
@@ -964,6 +967,7 @@ value called ``NULL`` for just this reason: from Python's perspective it
964967behaves like a default value of ``None ``, but the C variable is initialized
965968with ``NULL ``.
966969
970+
967971Expressions specified as default values
968972---------------------------------------
969973
@@ -1021,7 +1025,6 @@ you're not permitted to use:
10211025* Tuple/list/set/dict literals.
10221026
10231027
1024-
10251028Using a return converter
10261029------------------------
10271030
@@ -1140,6 +1143,7 @@ then modifying it. Cloning is an all-or nothing proposition.
11401143Also, the function you are cloning from must have been previously defined
11411144in the current file.
11421145
1146+
11431147Calling Python code
11441148-------------------
11451149
@@ -1374,6 +1378,7 @@ handle initialization and cleanup.
13741378You can see more examples of custom converters in the CPython
13751379source tree; grep the C files for the string ``CConverter ``.
13761380
1381+
13771382Writing a custom return converter
13781383---------------------------------
13791384
@@ -1388,8 +1393,9 @@ write your own return converter, please read ``Tools/clinic/clinic.py``,
13881393specifically the implementation of ``CReturnConverter `` and
13891394all its subclasses.
13901395
1396+
13911397METH_O and METH_NOARGS
1392- ----------------------------------------------
1398+ ----------------------
13931399
13941400To convert a function using ``METH_O ``, make sure the function's
13951401single argument is using the ``object `` converter, and mark the
@@ -1409,8 +1415,9 @@ any arguments.
14091415You can still use a self converter, a return converter, and specify
14101416a ``type `` argument to the object converter for ``METH_O ``.
14111417
1418+
14121419tp_new and tp_init functions
1413- ----------------------------------------------
1420+ ----------------------------
14141421
14151422You can convert ``tp_new `` and ``tp_init `` functions. Just name
14161423them ``__new__ `` or ``__init__ `` as appropriate. Notes:
@@ -1431,6 +1438,7 @@ them ``__new__`` or ``__init__`` as appropriate. Notes:
14311438 (If your function doesn't support keywords, the parsing function
14321439 generated will throw an exception if it receives any.)
14331440
1441+
14341442Changing and redirecting Clinic's output
14351443----------------------------------------
14361444
@@ -1715,7 +1723,7 @@ the file was not modified by hand before it gets overwritten.
17151723
17161724
17171725The #ifdef trick
1718- ----------------------------------------------
1726+ ----------------
17191727
17201728If you're converting a function that isn't available on all platforms,
17211729there's a trick you can use to make life a little easier. The existing
@@ -1795,7 +1803,6 @@ Argument Clinic added to your file (it'll be at the very bottom), then
17951803move it above the ``PyMethodDef `` structure where that macro is used.
17961804
17971805
1798-
17991806Using Argument Clinic in Python files
18001807-------------------------------------
18011808
0 commit comments