Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[3.11] Docs: Normalise Argument Clinic advanced topics headings (GH-106842) #106852

Merged
merged 1 commit into from
Jul 18, 2023
Merged

[3.11] Docs: Normalise Argument Clinic advanced topics headings (GH-106842) #106852

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 46 additions & 49 deletions Doc/howto/clinic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -552,15 +552,12 @@ Let's dive in!
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
expression. Currently the following are explicitly supported:
Expand All @@ -575,8 +572,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
Expand Down Expand Up @@ -618,8 +615,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
Expand All @@ -631,8 +628,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
Expand Down Expand Up @@ -724,8 +721,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
Expand Down Expand Up @@ -892,17 +889,17 @@ 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),
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.
Expand Down Expand Up @@ -933,8 +930,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:
Expand All @@ -957,8 +954,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
Expand All @@ -968,8 +965,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
Expand Down Expand Up @@ -1025,8 +1022,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>`.
Expand Down Expand Up @@ -1100,8 +1097,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,
Expand Down Expand Up @@ -1144,8 +1141,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
Expand All @@ -1172,8 +1169,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``
Expand Down Expand Up @@ -1224,8 +1221,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
Expand Down Expand Up @@ -1287,8 +1284,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``.
Expand Down Expand Up @@ -1379,8 +1376,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
Expand All @@ -1394,8 +1391,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
Expand All @@ -1416,8 +1413,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:
Expand All @@ -1439,8 +1436,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:
Expand Down Expand Up @@ -1722,8 +1719,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
Expand Down Expand Up @@ -1803,8 +1800,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
Expand Down