Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Docs: Normalise Argument Clinic advanced topics headings (#106842) 

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
This commit is contained in:
Erlend E. Aasland 2023-07-18 10:50:17 +02:00 committed by GitHub
parent 3e65baee72
commit 4cb0b9c0a9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 46 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
Doc/howto/clinic.rst
View File

@ -560,15 +560,12 @@ Let's dive in!
Congratulations, you've ported your first function to work with Argument Clinic! Congratulations, you've ported your first function to work with Argument Clinic!
Advanced topics How-to guides
=============== =============
Now that you've had some experience working with Argument Clinic, it's time
for some advanced topics.
Symbolic default values How to use symbolic default values
----------------------- ----------------------------------
The default value you provide for a parameter can't be any arbitrary The default value you provide for a parameter can't be any arbitrary
expression. Currently the following are explicitly supported: expression. Currently the following are explicitly supported:
@ -583,8 +580,8 @@ expression. Currently the following are explicitly supported:
to allow full expressions like ``CONSTANT - 1``.) to allow full expressions like ``CONSTANT - 1``.)
Renaming the C functions and variables generated by Argument Clinic How to to rename C functions and variables generated by Argument Clinic
------------------------------------------------------------------- -----------------------------------------------------------------------
Argument Clinic automatically names the functions it generates for you. Argument Clinic automatically names the functions it generates for you.
Occasionally this may cause a problem, if the generated name collides with Occasionally this may cause a problem, if the generated name collides with
@ -626,8 +623,8 @@ array) would be ``file``, but the C variable would be named ``file_obj``.
You can use this to rename the ``self`` parameter too! You can use this to rename the ``self`` parameter too!
Converting functions using PyArg_UnpackTuple How to convert functions using ``PyArg_UnpackTuple``
-------------------------------------------- ----------------------------------------------------
To convert a function parsing its arguments with :c:func:`PyArg_UnpackTuple`, To convert a function parsing its arguments with :c:func:`PyArg_UnpackTuple`,
simply write out all the arguments, specifying each as an ``object``. You simply write out all the arguments, specifying each as an ``object``. You
@ -639,8 +636,8 @@ Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this
will change soon. will change soon.
Optional groups How to use optional groups
--------------- --------------------------
Some legacy functions have a tricky approach to parsing their arguments: Some legacy functions have a tricky approach to parsing their arguments:
they count the number of positional arguments, then use a ``switch`` statement they count the number of positional arguments, then use a ``switch`` statement
@ -732,8 +729,8 @@ Notes:
use optional groups for new code. use optional groups for new code.
Using real Argument Clinic converters, instead of "legacy converters" How to use real Argument Clinic converters, instead of "legacy converters"
--------------------------------------------------------------------- --------------------------------------------------------------------------
To save time, and to minimize how much you need to learn To save time, and to minimize how much you need to learn
to achieve your first port to Argument Clinic, the walkthrough above tells to achieve your first port to Argument Clinic, the walkthrough above tells
@ -903,8 +900,8 @@ it accepts, along with the default value for each parameter.
Just run ``Tools/clinic/clinic.py --converters`` to see the full list. Just run ``Tools/clinic/clinic.py --converters`` to see the full list.
Py_buffer How to use the ``Py_buffer`` converter
--------- --------------------------------------
When using the ``Py_buffer`` converter When using the ``Py_buffer`` converter
(or the ``'s*'``, ``'w*'``, ``'*y'``, or ``'z*'`` legacy converters), (or the ``'s*'``, ``'w*'``, ``'*y'``, or ``'z*'`` legacy converters),
@ -912,8 +909,8 @@ you *must* not call :c:func:`PyBuffer_Release` on the provided buffer.
Argument Clinic generates code that does it for you (in the parsing function). Argument Clinic generates code that does it for you (in the parsing function).
Advanced converters How to use advanced converters
------------------- ------------------------------
Remember those format units you skipped for your first Remember those format units you skipped for your first
time because they were advanced? Here's how to handle those too. time because they were advanced? Here's how to handle those too.
@ -944,8 +941,8 @@ hard-coded encoding strings for parameters whose format units start with ``e``.
.. _default_values: .. _default_values:
Parameter default values How to assign default values to parameter
------------------------ -----------------------------------------
Default values for parameters can be any of a number of values. Default values for parameters can be any of a number of values.
At their simplest, they can be string, int, or float literals: At their simplest, they can be string, int, or float literals:
@ -968,8 +965,8 @@ There's also special support for a default value of ``NULL``, and
for simple expressions, documented in the following sections. for simple expressions, documented in the following sections.
The ``NULL`` default value How to use the ``NULL`` default value
-------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For string and object parameters, you can set them to ``None`` to indicate For string and object parameters, you can set them to ``None`` to indicate
that there's no default. However, that means the C variable will be that there's no default. However, that means the C variable will be
@ -979,8 +976,8 @@ behaves like a default value of ``None``, but the C variable is initialized
with ``NULL``. with ``NULL``.
Expressions specified as default values How to use expressions as default values
--------------------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default value for a parameter can be more than just a literal value. The default value for a parameter can be more than just a literal value.
It can be an entire expression, using math operators and looking up attributes It can be an entire expression, using math operators and looking up attributes
@ -1036,8 +1033,8 @@ you're not permitted to use:
* Tuple/list/set/dict literals. * Tuple/list/set/dict literals.
Using a return converter How to use return converters
------------------------ ----------------------------
By default, the impl function Argument Clinic generates for you returns By default, the impl function Argument Clinic generates for you returns
:c:type:`PyObject * <PyObject>`. :c:type:`PyObject * <PyObject>`.
@ -1106,8 +1103,8 @@ their parameters (if any),
just run ``Tools/clinic/clinic.py --converters`` for the full list. just run ``Tools/clinic/clinic.py --converters`` for the full list.
Cloning existing functions How to clone existing functions
-------------------------- -------------------------------
If you have a number of functions that look similar, you may be able to If you have a number of functions that look similar, you may be able to
use Clinic's "clone" feature. When you clone an existing function, use Clinic's "clone" feature. When you clone an existing function,
@ -1150,8 +1147,8 @@ Also, the function you are cloning from must have been previously defined
in the current file. in the current file.
Calling Python code How to call Python code
------------------- -----------------------
The rest of the advanced topics require you to write Python code The rest of the advanced topics require you to write Python code
which lives inside your C file and modifies Argument Clinic's which lives inside your C file and modifies Argument Clinic's
@ -1178,8 +1175,8 @@ variable to the C code::
/*[python checksum:...]*/ /*[python checksum:...]*/
Using a "self converter" How to use the "self converter"
------------------------ -------------------------------
Argument Clinic automatically adds a "self" parameter for you Argument Clinic automatically adds a "self" parameter for you
using a default converter. It automatically sets the ``type`` using a default converter. It automatically sets the ``type``
@ -1230,8 +1227,8 @@ type for ``self``, it's best to create your own converter, subclassing
[clinic start generated code]*/ [clinic start generated code]*/
Using a "defining class" converter How to use the "defining class" converter
---------------------------------- -----------------------------------------
Argument Clinic facilitates gaining access to the defining class of a method. Argument Clinic facilitates gaining access to the defining class of a method.
This is useful for :ref:`heap type <heap-types>` methods that need to fetch This is useful for :ref:`heap type <heap-types>` methods that need to fetch
@ -1293,8 +1290,8 @@ state. Example from the ``setattro`` slot method in
See also :pep:`573`. See also :pep:`573`.
Writing a custom converter How to write a custom converter
-------------------------- -------------------------------
As we hinted at in the previous section... you can write your own converters! As we hinted at in the previous section... you can write your own converters!
A converter is simply a Python class that inherits from ``CConverter``. A converter is simply a Python class that inherits from ``CConverter``.
@ -1385,8 +1382,8 @@ You can see more examples of custom converters in the CPython
source tree; grep the C files for the string ``CConverter``. source tree; grep the C files for the string ``CConverter``.
Writing a custom return converter How to write a custom return converter
--------------------------------- --------------------------------------
Writing a custom return converter is much like writing Writing a custom return converter is much like writing
a custom converter. Except it's somewhat simpler, because return a custom converter. Except it's somewhat simpler, because return
@ -1400,8 +1397,8 @@ specifically the implementation of ``CReturnConverter`` and
all its subclasses. all its subclasses.
METH_O and METH_NOARGS How to convert ``METH_O`` and ``METH_NOARGS`` functions
---------------------- -------------------------------------------------------
To convert a function using ``METH_O``, make sure the function's To convert a function using ``METH_O``, make sure the function's
single argument is using the ``object`` converter, and mark the single argument is using the ``object`` converter, and mark the
@ -1422,8 +1419,8 @@ You can still use a self converter, a return converter, and specify
a ``type`` argument to the object converter for ``METH_O``. a ``type`` argument to the object converter for ``METH_O``.
tp_new and tp_init functions How to convert ``tp_new`` and ``tp_init`` functions
---------------------------- ---------------------------------------------------
You can convert ``tp_new`` and ``tp_init`` functions. Just name You can convert ``tp_new`` and ``tp_init`` functions. Just name
them ``__new__`` or ``__init__`` as appropriate. Notes: them ``__new__`` or ``__init__`` as appropriate. Notes:
@ -1445,8 +1442,8 @@ them ``__new__`` or ``__init__`` as appropriate. Notes:
generated will throw an exception if it receives any.) generated will throw an exception if it receives any.)
Changing and redirecting Clinic's output How to change and redirect Clinic's output
---------------------------------------- ------------------------------------------
It can be inconvenient to have Clinic's output interspersed with It can be inconvenient to have Clinic's output interspersed with
your conventional hand-edited C code. Luckily, Clinic is configurable: your conventional hand-edited C code. Luckily, Clinic is configurable:
@ -1728,8 +1725,8 @@ it in a Clinic block lets Clinic use its existing checksum functionality to ensu
the file was not modified by hand before it gets overwritten. the file was not modified by hand before it gets overwritten.
The #ifdef trick How to use the ``#ifdef`` trick
---------------- -------------------------------
If you're converting a function that isn't available on all platforms, If you're converting a function that isn't available on all platforms,
there's a trick you can use to make life a little easier. The existing there's a trick you can use to make life a little easier. The existing
@ -1809,8 +1806,8 @@ Argument Clinic added to your file (it'll be at the very bottom), then
move it above the ``PyMethodDef`` structure where that macro is used. move it above the ``PyMethodDef`` structure where that macro is used.
Using Argument Clinic in Python files How to use Argument Clinic in Python files
------------------------------------- ------------------------------------------
It's actually possible to use Argument Clinic to preprocess Python files. It's actually possible to use Argument Clinic to preprocess Python files.
There's no point to using Argument Clinic blocks, of course, as the output There's no point to using Argument Clinic blocks, of course, as the output