1
+ .. highlightlang :: c
2
+
1
3
**********************
2
4
Argument Clinic How-To
3
5
**********************
@@ -78,17 +80,23 @@ Basic Concepts And Usage
78
80
========================
79
81
80
82
Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py ``.
81
- If you run that script, specifying a C file as an argument::
83
+ If you run that script, specifying a C file as an argument:
84
+
85
+ .. code-block :: shell-session
82
86
83
- % python3 Tools/clinic/clinic.py foo.c
87
+ $ python3 Tools/clinic/clinic.py foo.c
84
88
85
89
Argument Clinic will scan over the file looking for lines that
86
- look exactly like this::
90
+ look exactly like this:
91
+
92
+ .. code-block :: none
87
93
88
94
/*[clinic input]
89
95
90
96
When it finds one, it reads everything up to a line that looks
91
- exactly like this::
97
+ exactly like this:
98
+
99
+ .. code-block :: none
92
100
93
101
[clinic start generated code]*/
94
102
@@ -99,7 +107,9 @@ lines, are collectively called an Argument Clinic "block".
99
107
When Argument Clinic parses one of these blocks, it
100
108
generates output. This output is rewritten into the C file
101
109
immediately after the block, followed by a comment containing a checksum.
102
- The Argument Clinic block now looks like this::
110
+ The Argument Clinic block now looks like this:
111
+
112
+ .. code-block :: none
103
113
104
114
/*[clinic input]
105
115
... clinic input goes here ...
@@ -375,15 +385,10 @@ Let's dive in!
375
385
Write a pickled representation of obj to the open file.
376
386
[clinic start generated code]*/
377
387
378
- 12. Save and close the file, then run ``Tools/clinic/clinic.py `` on it.
379
- With luck everything worked and your block now has output! Reopen
380
- the file in your text editor to see::
381
-
382
- /*[clinic input]
383
- module _pickle
384
- class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
385
- [clinic start generated code]*/
386
- /*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
388
+ 12. Save and close the file, then run ``Tools/clinic/clinic.py `` on
389
+ it. With luck everything worked---your block now has output, and
390
+ a ``.c.h `` file has been generated! Reopen the file in your
391
+ text editor to see::
387
392
388
393
/*[clinic input]
389
394
_pickle.Pickler.dump
@@ -395,18 +400,20 @@ Let's dive in!
395
400
Write a pickled representation of obj to the open file.
396
401
[clinic start generated code]*/
397
402
398
- PyDoc_STRVAR(_pickle_Pickler_dump__doc__,
399
- "Write a pickled representation of obj to the open file.\n"
400
- "\n"
401
- ...
402
403
static PyObject *
403
- _pickle_Pickler_dump_impl (PicklerObject *self, PyObject *obj)
404
- /*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187 ]*/
404
+ _pickle_Pickler_dump (PicklerObject *self, PyObject *obj)
405
+ /*[clinic end generated code: output=87ecad1261e02ac7 input=552eb1c0f52260d9 ]*/
405
406
406
407
Obviously, if Argument Clinic didn't produce any output, it's because
407
408
it found an error in your input. Keep fixing your errors and retrying
408
409
until Argument Clinic processes your file without complaint.
409
410
411
+ For readability, most of the glue code has been generated to a ``.c.h ``
412
+ file. You'll need to include that in your original ``.c `` file,
413
+ typically right after the clinic module block::
414
+
415
+ #include "clinic/_pickle.c.h"
416
+
410
417
13. Double-check that the argument-parsing code Argument Clinic generated
411
418
looks basically the same as the existing code.
412
419
@@ -1027,7 +1034,9 @@ that value, and an error has been set (``PyErr_Occurred()`` returns a true
1027
1034
value), then the generated code will propagate the error. Otherwise it will
1028
1035
encode the value you return like normal.
1029
1036
1030
- Currently Argument Clinic supports only a few return converters::
1037
+ Currently Argument Clinic supports only a few return converters:
1038
+
1039
+ .. code-block :: none
1031
1040
1032
1041
bool
1033
1042
int
@@ -1606,7 +1615,9 @@ code probably looks like this::
1606
1615
#endif /* HAVE_FUNCTIONNAME */
1607
1616
1608
1617
And then in the ``PyMethodDef `` structure at the bottom the existing code
1609
- will have::
1618
+ will have:
1619
+
1620
+ .. code-block :: none
1610
1621
1611
1622
#ifdef HAVE_FUNCTIONNAME
1612
1623
{'functionname', ... },
@@ -1656,7 +1667,9 @@ extra code when using the "block" output preset? It can't go in the output bloc
1656
1667
because that could be deactivated by the ``#ifdef ``. (That's the whole point!)
1657
1668
1658
1669
In this situation, Argument Clinic writes the extra code to the "buffer" destination.
1659
- This may mean that you get a complaint from Argument Clinic::
1670
+ This may mean that you get a complaint from Argument Clinic:
1671
+
1672
+ .. code-block :: none
1660
1673
1661
1674
Warning in file "Modules/posixmodule.c" on line 12357:
1662
1675
Destination buffer 'buffer' not empty at end of file, emptying.
@@ -1676,7 +1689,9 @@ wouldn't make any sense to the Python interpreter. But using Argument Clinic
1676
1689
to run Python blocks lets you use Python as a Python preprocessor!
1677
1690
1678
1691
Since Python comments are different from C comments, Argument Clinic
1679
- blocks embedded in Python files look slightly different. They look like this::
1692
+ blocks embedded in Python files look slightly different. They look like this:
1693
+
1694
+ .. code-block :: python3
1680
1695
1681
1696
#/*[python input]
1682
1697
#print("def foo(): pass")
0 commit comments