diff options
author | Martin Panter <vadmium+py@gmail.com> | 2016-12-10 04:14:02 (GMT) |
---|---|---|
committer | Martin Panter <vadmium+py@gmail.com> | 2016-12-10 04:14:02 (GMT) |
commit | 2fed8cd6f0f8c1708cc266c7c425a09a1be4b554 (patch) | |
tree | 9f4c1736849411cdebe4862163d887078296fd50 | |
parent | f44abdab1eeb75e2a876e905e3af20b461ab0f6c (diff) | |
parent | cfa9bad4b22c30f208e3b430dcd3db4e5f8cf0e1 (diff) | |
download | cpython-2fed8cd6f0f8c1708cc266c7c425a09a1be4b554.zip cpython-2fed8cd6f0f8c1708cc266c7c425a09a1be4b554.tar.gz cpython-2fed8cd6f0f8c1708cc266c7c425a09a1be4b554.tar.bz2 |
Issues #28755, #28753: Merge Arg Clinic howto from 3.5
-rw-r--r-- | Doc/howto/clinic.rst | 63 |
1 files changed, 39 insertions, 24 deletions
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 4742d84..eaab20a 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1,3 +1,5 @@ +.. highlightlang:: c + ********************** Argument Clinic How-To ********************** @@ -78,17 +80,23 @@ Basic Concepts And Usage ======================== Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py``. -If you run that script, specifying a C file as an argument:: +If you run that script, specifying a C file as an argument: + +.. code-block:: shell-session - % python3 Tools/clinic/clinic.py foo.c + $ python3 Tools/clinic/clinic.py foo.c Argument Clinic will scan over the file looking for lines that -look exactly like this:: +look exactly like this: + +.. code-block:: none /*[clinic input] When it finds one, it reads everything up to a line that looks -exactly like this:: +exactly like this: + +.. code-block:: none [clinic start generated code]*/ @@ -99,7 +107,9 @@ lines, are collectively called an Argument Clinic "block". When Argument Clinic parses one of these blocks, it 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:: +The Argument Clinic block now looks like this: + +.. code-block:: none /*[clinic input] ... clinic input goes here ... @@ -375,15 +385,10 @@ Let's dive in! Write a pickled representation of obj to the open file. [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 input] - module _pickle - class _pickle.Pickler "PicklerObject *" "&Pickler_Type" - [clinic start generated code]*/ - /*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/ +12. Save and close the file, then run ``Tools/clinic/clinic.py`` on + it. With luck everything worked---your block now has output, and + a ``.c.h`` file has been generated! Reopen the file in your + text editor to see:: /*[clinic input] _pickle.Pickler.dump @@ -395,18 +400,20 @@ Let's dive in! Write a pickled representation of obj to the open file. [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(PicklerObject *self, PyObject *obj) - /*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/ + _pickle_Pickler_dump(PicklerObject *self, PyObject *obj) + /*[clinic end generated code: output=87ecad1261e02ac7 input=552eb1c0f52260d9]*/ 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 until Argument Clinic processes your file without complaint. + For readability, most of the glue code has been generated to a ``.c.h`` + file. You'll need to include that in your original ``.c`` file, + typically right after the clinic module block:: + + #include "clinic/_pickle.c.h" + 13. Double-check that the argument-parsing code Argument Clinic generated looks basically the same as the existing code. @@ -1027,7 +1034,9 @@ that value, and an error has been set (``PyErr_Occurred()`` returns a true value), then the generated code will propagate the error. Otherwise it will encode the value you return like normal. -Currently Argument Clinic supports only a few return converters:: +Currently Argument Clinic supports only a few return converters: + +.. code-block:: none bool int @@ -1606,7 +1615,9 @@ code probably looks like this:: #endif /* HAVE_FUNCTIONNAME */ And then in the ``PyMethodDef`` structure at the bottom the existing code -will have:: +will have: + +.. code-block:: none #ifdef HAVE_FUNCTIONNAME {'functionname', ... }, @@ -1656,7 +1667,9 @@ extra code when using the "block" output preset? It can't go in the output bloc because that could be deactivated by the ``#ifdef``. (That's the whole point!) In this situation, Argument Clinic writes the extra code to the "buffer" destination. -This may mean that you get a complaint from Argument Clinic:: +This may mean that you get a complaint from Argument Clinic: + +.. code-block:: none Warning in file "Modules/posixmodule.c" on line 12357: 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 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:: +blocks embedded in Python files look slightly different. They look like this: + +.. code-block:: python3 #/*[python input] #print("def foo(): pass") |