Skip to content

Commit

Permalink
Issue python#19273: The marker comments Argument Clinic uses have bee…
Browse files Browse the repository at this point in the history 
…n changed

to improve readability.
  • Loading branch information
@larryhastings
larryhastings committed Jan 7, 2014
1 parent 9026113 commit 61272b7
Show file tree
Hide file tree
Showing 14 changed files with 220 additions and 216 deletions.
126 changes: 63 additions & 63 deletions Doc/howto/clinic.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ If you run that script, specifying a C file as an argument::
Argument Clinic will scan over the file looking for lines that
look exactly like this::

/*[clinic]
/*[clinic input]

When it finds one, it reads everything up to a line that looks
like this::
exactly like this::

[clinic]*/
[clinic start generated code]*/

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

/*[clinic]
/*[clinic input]
... clinic input goes here ...
[clinic]*/
[clinic start generated code]*/
... clinic output goes here ...
/*[clinic checksum:...]*/
/*[clinic end generated code: checksum=...]*/

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

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

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

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

/*[clinic]
[clinic]*/
/*[clinic input]
[clinic start generated code]*/

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

Sample::

/*[clinic]
/*[clinic input]
Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/

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

Sample::

/*[clinic]
/*[clinic input]
pickle.Pickler.dump

Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/

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

Sample::

/*[clinic]
/*[clinic input]
module pickle
class pickle.Pickler
[clinic]*/
[clinic start generated code]*/

/*[clinic]
/*[clinic input]
pickle.Pickler.dump

Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/


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

Sample::

/*[clinic]
/*[clinic input]
module pickle
class pickle.Pickler
[clinic]*/
[clinic start generated code]*/

/*[clinic]
/*[clinic input]
pickle.Pickler.dump

obj: 'O'

Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/

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

Sample::

/*[clinic]
/*[clinic input]
module pickle
class pickle.Pickler
[clinic]*/
[clinic start generated code]*/

/*[clinic]
/*[clinic input]
pickle.Pickler.dump

obj: 'O'
/

Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/

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

Sample::

/*[clinic]
/*[clinic input]
module pickle
class pickle.Pickler
[clinic]*/
[clinic start generated code]*/

/*[clinic]
/*[clinic input]
pickle.Pickler.dump

obj: 'O'
The object to be pickled.
/

Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/

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

/*[clinic]
/*[clinic input]
module pickle
class pickle.Pickler
[clinic]*/
/*[clinic checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
[clinic start generated code]*/
/*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

/*[clinic]
/*[clinic input]
pickle.Pickler.dump

obj: 'O'
The object to be pickled.
/

Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/

PyDoc_STRVAR(pickle_Pickler_dump__doc__,
"Write a pickled representation of obj to the open file.\n"
"\n"
...
static PyObject *
pickle_Pickler_dump_impl(PyObject *self, PyObject *obj)
/*[clinic checksum: 3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
/*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/

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

static return_type
your_function_impl(...)
/*[clinic checksum: ...]*/
/*[clinic end generated code: checksum=...]*/
{
...

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

Sample::

/*[clinic]
/*[clinic input]
module pickle
class pickle.Pickler
[clinic]*/
/*[clinic checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
[clinic start generated code]*/
/*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

/*[clinic]
/*[clinic input]
pickle.Pickler.dump

obj: 'O'
The object to be pickled.
/

Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/

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

/*[clinic]
/*[clinic input]
pickle.Pickler.dump as pickler_dumper

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

/*[clinic]
/*[clinic input]

curses.window.addch

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

/*[clinic]
/*[clinic input]
pickle.Pickler.dump

obj: object
The object to be pickled.
/

Write a pickled representation of obj to the open file.
[clinic]*/
[clinic start generated code]*/

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

/*[python]
/*[python input]
# python code goes here
[python]*/
[python start generated code]*/

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

/*[python]
/*[python input]
print('static int __ignored_unused_variable__ = 0;')
[python]*/
[python start generated code]*/
static int __ignored_unused_variable__ = 0;
/*[python checksum:...]*/

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

/*[clinic]
/*[clinic input]

_pickle.Pickler.dump

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

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

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

/*[clinic]
/*[clinic input]
class PicklerObject_converter(self_converter):
type = "PicklerObject *"
[clinic]*/
[clinic start generated code]*/

/*[clinic]
/*[clinic input]

_pickle.Pickler.dump

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

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



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

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

/*[python]
/*[python input]

class uint_converter(CConverter):
type = 'unsigned int'
converter = 'uint_converter'

[python]*/
/*[python checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
[python start generated code]*/
/*[python end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

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

#/*[python]
#/*[python input]
#print("def foo(): pass")
#[python]*/
#[python start generated code]*/
def foo(): pass
#/*[python checksum:...]*/
3 changes: 3 additions & 0 deletions Misc/NEWS
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,9 @@ Library
Tools/Demos
-----------

- Issue #19273: The marker comments Argument Clinic uses have been changed
to improve readability.

- Issue #20157: When Argument Clinic renames a parameter because its name
collides with a C keyword, it no longer exposes that rename to PyArg_Parse.

Expand Down
Loading

0 comments on commit 61272b7

Please sign in to comment.