Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 61272b7

Browse files
larryhastingslarryhastings
committed
Issue #19273: The marker comments Argument Clinic uses have been changed
to improve readability.
1 parent 9026113 commit 61272b7

14 files changed

Lines changed: 220 additions & 216 deletions

File tree

‎Doc/howto/clinic.rst‎

Lines changed: 63 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,12 @@ If you run that script, specifying a C file as an argument::
3535
Argument Clinic will scan over the file looking for lines that
3636
look exactly like this::
3737

38-
/*[clinic]
38+
/*[clinic input]
3939

4040
When it finds one, it reads everything up to a line that looks
41-
like this::
41+
exactly like this::
4242

43-
[clinic]*/
43+
[clinic start generated code]*/
4444

4545
Everything in between these two lines is input for Argument Clinic.
4646
All of these lines, including the beginning and ending comment
@@ -51,11 +51,11 @@ generates output. This output is rewritten into the C file
5151
immediately after the block, followed by a comment containing a checksum.
5252
The Argument Clinic block now looks like this::
5353

54-
/*[clinic]
54+
/*[clinic input]
5555
... clinic input goes here ...
56-
[clinic]*/
56+
[clinic start generated code]*/
5757
... clinic output goes here ...
58-
/*[clinic checksum:...]*/
58+
/*[clinic end generated code: checksum=...]*/
5959

6060
If you run Argument Clinic on the same file a second time, Argument Clinic
6161
will discard the old output and write out the new output with a fresh checksum
@@ -68,9 +68,9 @@ the next time Argument Clinic writes out fresh output.)
6868

6969
For the sake of clarity, here's the terminology we'll use with Argument Clinic:
7070

71-
* The first line of the comment (``/*[clinic]``) is the *start line*.
72-
* The last line of the initial comment (``[clinic]*/``) is the *end line*.
73-
* The last line (``/*[clinic checksum:...]*/``) is the *checksum line*.
71+
* The first line of the comment (``/*[clinic input]``) is the *start line*.
72+
* The last line of the initial comment (``[clinic start generated code]*/``) is the *end line*.
73+
* The last line (``/*[clinic end generated code: checksum=...]*/``) is the *checksum line*.
7474
* In between the start line and the end line is the *input*.
7575
* In between the end line and the checksum line is the *output*.
7676
* All the text collectively, from the start line to the checksum line inclusively,
@@ -111,8 +111,8 @@ convert a function to work with it. Let's dive in!
111111

112112
3. Add the following boilerplate above the function, creating our block::
113113

114-
/*[clinic]
115-
[clinic]*/
114+
/*[clinic input]
115+
[clinic start generated code]*/
116116

117117
4. Cut the docstring and paste it in between the ``[clinic]`` lines,
118118
removing all the junk that makes it a properly quoted C string.
@@ -122,9 +122,9 @@ convert a function to work with it. Let's dive in!
122122

123123
Sample::
124124

125-
/*[clinic]
125+
/*[clinic input]
126126
Write a pickled representation of obj to the open file.
127-
[clinic]*/
127+
[clinic start generated code]*/
128128

129129
5. If your docstring doesn't have a "summary" line, Argument Clinic will
130130
complain. So let's make sure it has one. The "summary" line should
@@ -143,11 +143,11 @@ convert a function to work with it. Let's dive in!
143143

144144
Sample::
145145

146-
/*[clinic]
146+
/*[clinic input]
147147
pickle.Pickler.dump
148148

149149
Write a pickled representation of obj to the open file.
150-
[clinic]*/
150+
[clinic start generated code]*/
151151

152152
7. If this is the first time that module or class has been used with Argument
153153
Clinic in this C file,
@@ -159,16 +159,16 @@ convert a function to work with it. Let's dive in!
159159

160160
Sample::
161161

162-
/*[clinic]
162+
/*[clinic input]
163163
module pickle
164164
class pickle.Pickler
165-
[clinic]*/
165+
[clinic start generated code]*/
166166

167-
/*[clinic]
167+
/*[clinic input]
168168
pickle.Pickler.dump
169169

170170
Write a pickled representation of obj to the open file.
171-
[clinic]*/
171+
[clinic start generated code]*/
172172

173173

174174
8. Declare each of the parameters to the function. Each parameter
@@ -207,18 +207,18 @@ convert a function to work with it. Let's dive in!
207207

208208
Sample::
209209

210-
/*[clinic]
210+
/*[clinic input]
211211
module pickle
212212
class pickle.Pickler
213-
[clinic]*/
213+
[clinic start generated code]*/
214214

215-
/*[clinic]
215+
/*[clinic input]
216216
pickle.Pickler.dump
217217

218218
obj: 'O'
219219

220220
Write a pickled representation of obj to the open file.
221-
[clinic]*/
221+
[clinic start generated code]*/
222222

223223
9. If your function has ``|`` in the format string, meaning some
224224
parameters have default values, you can ignore it. Argument
@@ -247,19 +247,19 @@ convert a function to work with it. Let's dive in!
247247

248248
Sample::
249249

250-
/*[clinic]
250+
/*[clinic input]
251251
module pickle
252252
class pickle.Pickler
253-
[clinic]*/
253+
[clinic start generated code]*/
254254

255-
/*[clinic]
255+
/*[clinic input]
256256
pickle.Pickler.dump
257257

258258
obj: 'O'
259259
/
260260

261261
Write a pickled representation of obj to the open file.
262-
[clinic]*/
262+
[clinic start generated code]*/
263263

264264
11. It's helpful to write a per-parameter docstring for each parameter.
265265
But per-parameter docstrings are optional; you can skip this step
@@ -274,48 +274,48 @@ convert a function to work with it. Let's dive in!
274274

275275
Sample::
276276

277-
/*[clinic]
277+
/*[clinic input]
278278
module pickle
279279
class pickle.Pickler
280-
[clinic]*/
280+
[clinic start generated code]*/
281281

282-
/*[clinic]
282+
/*[clinic input]
283283
pickle.Pickler.dump
284284

285285
obj: 'O'
286286
The object to be pickled.
287287
/
288288

289289
Write a pickled representation of obj to the open file.
290-
[clinic]*/
290+
[clinic start generated code]*/
291291

292292
12. Save and close the file, then run ``Tools/clinic/clinic.py`` on it.
293293
With luck everything worked and your block now has output! Reopen
294294
the file in your text editor to see::
295295

296-
/*[clinic]
296+
/*[clinic input]
297297
module pickle
298298
class pickle.Pickler
299-
[clinic]*/
300-
/*[clinic checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
299+
[clinic start generated code]*/
300+
/*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
301301

302-
/*[clinic]
302+
/*[clinic input]
303303
pickle.Pickler.dump
304304

305305
obj: 'O'
306306
The object to be pickled.
307307
/
308308

309309
Write a pickled representation of obj to the open file.
310-
[clinic]*/
310+
[clinic start generated code]*/
311311

312312
PyDoc_STRVAR(pickle_Pickler_dump__doc__,
313313
"Write a pickled representation of obj to the open file.\n"
314314
"\n"
315315
...
316316
static PyObject *
317317
pickle_Pickler_dump_impl(PyObject *self, PyObject *obj)
318-
/*[clinic checksum: 3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
318+
/*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
319319

320320
Obviously, if Argument Clinic didn't produce any output, it's because
321321
it found an error in your input. Keep fixing your errors and retrying
@@ -373,7 +373,7 @@ convert a function to work with it. Let's dive in!
373373

374374
static return_type
375375
your_function_impl(...)
376-
/*[clinic checksum: ...]*/
376+
/*[clinic end generated code: checksum=...]*/
377377
{
378378
...
379379

@@ -383,29 +383,29 @@ convert a function to work with it. Let's dive in!
383383

384384
Sample::
385385

386-
/*[clinic]
386+
/*[clinic input]
387387
module pickle
388388
class pickle.Pickler
389-
[clinic]*/
390-
/*[clinic checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
389+
[clinic start generated code]*/
390+
/*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
391391

392-
/*[clinic]
392+
/*[clinic input]
393393
pickle.Pickler.dump
394394

395395
obj: 'O'
396396
The object to be pickled.
397397
/
398398

399399
Write a pickled representation of obj to the open file.
400-
[clinic]*/
400+
[clinic start generated code]*/
401401

402402
PyDoc_STRVAR(pickle_Pickler_dump__doc__,
403403
"Write a pickled representation of obj to the open file.\n"
404404
"\n"
405405
...
406406
static PyObject *
407407
pickle_Pickler_dump_impl(PyObject *self, PyObject *obj)
408-
/*[clinic checksum: 3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
408+
/*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
409409
{
410410
/* Check whether the Pickler was initialized correctly (issue3664).
411411
Developers often forget to call __init__() in their subclasses, which
@@ -470,7 +470,7 @@ then add ``"_impl"`` to the end and use that for the name of the impl function.
470470
For example, if we wanted to rename the C function names generated for
471471
``pickle.Pickler.dump``, it'd look like this::
472472

473-
/*[clinic]
473+
/*[clinic input]
474474
pickle.Pickler.dump as pickler_dumper
475475

476476
...
@@ -515,7 +515,7 @@ after these parameters. As an example, here's how ``curses.window.addch``
515515
uses optional groups to make the first two parameters and the last
516516
parameter optional::
517517

518-
/*[clinic]
518+
/*[clinic input]
519519

520520
curses.window.addch
521521

@@ -666,15 +666,15 @@ on the right is the text you'd replace it with.
666666
As an example, here's our sample ``pickle.Pickler.dump`` using the proper
667667
converter::
668668

669-
/*[clinic]
669+
/*[clinic input]
670670
pickle.Pickler.dump
671671

672672
obj: object
673673
The object to be pickled.
674674
/
675675

676676
Write a pickled representation of obj to the open file.
677-
[clinic]*/
677+
[clinic start generated code]*/
678678

679679
Argument Clinic will show you all the converters it has
680680
available. For each converter it'll show you all the parameters
@@ -769,9 +769,9 @@ runtime state. This is simple: you simply define a Python block.
769769
A Python block uses different delimiter lines than an Argument
770770
Clinic function block. It looks like this::
771771

772-
/*[python]
772+
/*[python input]
773773
# python code goes here
774-
[python]*/
774+
[python start generated code]*/
775775

776776
All the code inside the Python block is executed at the
777777
time it's parsed. All text written to stdout inside the block
@@ -780,9 +780,9 @@ is redirected into the "output" after the block.
780780
As an example, here's a Python block that adds a static integer
781781
variable to the C code::
782782

783-
/*[python]
783+
/*[python input]
784784
print('static int __ignored_unused_variable__ = 0;')
785-
[python]*/
785+
[python start generated code]*/
786786
static int __ignored_unused_variable__ = 0;
787787
/*[python checksum:...]*/
788788

@@ -806,7 +806,7 @@ If you only have one or two functions with the same type for ``self``,
806806
you can directly use Argument Clinic's existing ``self`` converter,
807807
passing in the type you want to use as the ``type`` parameter::
808808

809-
/*[clinic]
809+
/*[clinic input]
810810

811811
_pickle.Pickler.dump
812812

@@ -815,18 +815,18 @@ passing in the type you want to use as the ``type`` parameter::
815815
/
816816

817817
Write a pickled representation of the given object to the open file.
818-
[clinic]*/
818+
[clinic start generated code]*/
819819

820820
On the other hand, if you have a lot of functions that will use the same
821821
type for ``self``, it's best to create your own converter, subclassing
822822
``self_converter`` but overwriting the ``type`` member::
823823

824-
/*[clinic]
824+
/*[clinic input]
825825
class PicklerObject_converter(self_converter):
826826
type = "PicklerObject *"
827-
[clinic]*/
827+
[clinic start generated code]*/
828828

829-
/*[clinic]
829+
/*[clinic input]
830830

831831
_pickle.Pickler.dump
832832

@@ -835,7 +835,7 @@ type for ``self``, it's best to create your own converter, subclassing
835835
/
836836

837837
Write a pickled representation of the given object to the open file.
838-
[clinic]*/
838+
[clinic start generated code]*/
839839

840840

841841

@@ -917,14 +917,14 @@ to specify in your subclass. Here's the current list:
917917

918918
Here's the simplest example of a custom converter, from ``Modules/zlibmodule.c``::
919919

920-
/*[python]
920+
/*[python input]
921921

922922
class uint_converter(CConverter):
923923
type = 'unsigned int'
924924
converter = 'uint_converter'
925925

926-
[python]*/
927-
/*[python checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
926+
[python start generated code]*/
927+
/*[python end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
928928

929929
This block adds a converter to Argument Clinic named ``uint``. Parameters
930930
declared as ``uint`` will be declared as type ``unsigned int``, and will
@@ -963,8 +963,8 @@ to run Python blocks lets you use Python as a Python preprocessor!
963963
Since Python comments are different from C comments, Argument Clinic
964964
blocks embedded in Python files look slightly different. They look like this::
965965

966-
#/*[python]
966+
#/*[python input]
967967
#print("def foo(): pass")
968-
#[python]*/
968+
#[python start generated code]*/
969969
def foo(): pass
970970
#/*[python checksum:...]*/

‎Misc/NEWS‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,9 @@ Library
2121
Tools/Demos
2222
-----------
2323

24+
- Issue #19273: The marker comments Argument Clinic uses have been changed
25+
to improve readability.
26+
2427
- Issue #20157: When Argument Clinic renames a parameter because its name
2528
collides with a C keyword, it no longer exposes that rename to PyArg_Parse.
2629

0 commit comments

Comments
 (0)