mirror of https://github.com/python/cpython
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
GitHub
parent
3e65baee72
commit
4cb0b9c0a9
|
|
@ -560,15 +560,12 @@ Let's dive in!
|
|||
Congratulations, you've ported your first function to work with Argument Clinic!
|
||||
|
||||
|
||||
Advanced topics
|
||||
===============
|
||||
|
||||
Now that you've had some experience working with Argument Clinic, it's time
|
||||
for some advanced topics.
|
||||
How-to guides
|
||||
=============
|
||||
|
||||
|
||||
Symbolic default values
|
||||
-----------------------
|
||||
How to use symbolic default values
|
||||
----------------------------------
|
||||
|
||||
The default value you provide for a parameter can't be any arbitrary
|
||||
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``.)
|
||||
|
||||
|
||||
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.
|
||||
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!
|
||||
|
||||
|
||||
Converting functions using PyArg_UnpackTuple
|
||||
--------------------------------------------
|
||||
How to convert functions using ``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
|
||||
|
|
@ -639,8 +636,8 @@ Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this
|
|||
will change soon.
|
||||
|
||||
|
||||
Optional groups
|
||||
---------------
|
||||
How to use optional groups
|
||||
--------------------------
|
||||
|
||||
Some legacy functions have a tricky approach to parsing their arguments:
|
||||
they count the number of positional arguments, then use a ``switch`` statement
|
||||
|
|
@ -732,8 +729,8 @@ Notes:
|
|||
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 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.
|
||||
|
||||
|
||||
Py_buffer
|
||||
---------
|
||||
How to use the ``Py_buffer`` converter
|
||||
--------------------------------------
|
||||
|
||||
When using the ``Py_buffer`` converter
|
||||
(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).
|
||||
|
||||
|
||||
Advanced converters
|
||||
-------------------
|
||||
How to use advanced converters
|
||||
------------------------------
|
||||
|
||||
Remember those format units you skipped for your first
|
||||
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:
|
||||
|
||||
Parameter default values
|
||||
------------------------
|
||||
How to assign default values to parameter
|
||||
-----------------------------------------
|
||||
|
||||
Default values for parameters can be any of a number of values.
|
||||
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.
|
||||
|
||||
|
||||
The ``NULL`` default value
|
||||
--------------------------
|
||||
How to use the ``NULL`` default value
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
|
|
@ -979,8 +976,8 @@ behaves like a default value of ``None``, but the C variable is initialized
|
|||
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.
|
||||
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.
|
||||
|
||||
|
||||
Using a return converter
|
||||
------------------------
|
||||
How to use return converters
|
||||
----------------------------
|
||||
|
||||
By default, the impl function Argument Clinic generates for you returns
|
||||
:c:type:`PyObject * <PyObject>`.
|
||||
|
|
@ -1106,8 +1103,8 @@ their parameters (if any),
|
|||
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
|
||||
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.
|
||||
|
||||
|
||||
Calling Python code
|
||||
-------------------
|
||||
How to call 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
|
||||
|
|
@ -1178,8 +1175,8 @@ variable to the C code::
|
|||
/*[python checksum:...]*/
|
||||
|
||||
|
||||
Using a "self converter"
|
||||
------------------------
|
||||
How to use the "self converter"
|
||||
-------------------------------
|
||||
|
||||
Argument Clinic automatically adds a "self" parameter for you
|
||||
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]*/
|
||||
|
||||
|
||||
Using a "defining class" converter
|
||||
----------------------------------
|
||||
How to use the "defining class" converter
|
||||
-----------------------------------------
|
||||
|
||||
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
|
||||
|
|
@ -1293,8 +1290,8 @@ state. Example from the ``setattro`` slot method in
|
|||
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!
|
||||
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``.
|
||||
|
||||
|
||||
Writing a custom return converter
|
||||
---------------------------------
|
||||
How to write a custom return converter
|
||||
--------------------------------------
|
||||
|
||||
Writing a custom return converter is much like writing
|
||||
a custom converter. Except it's somewhat simpler, because return
|
||||
|
|
@ -1400,8 +1397,8 @@ specifically the implementation of ``CReturnConverter`` and
|
|||
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
|
||||
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``.
|
||||
|
||||
|
||||
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
|
||||
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.)
|
||||
|
||||
|
||||
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
|
||||
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 #ifdef trick
|
||||
----------------
|
||||
How to use the ``#ifdef`` trick
|
||||
-------------------------------
|
||||
|
||||
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
|
||||
|
|
@ -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.
|
||||
|
||||
|
||||
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.
|
||||
There's no point to using Argument Clinic blocks, of course, as the output
|
||||
|
|
|
|||
Loading…
Reference in New Issue