[Python-checkins] [3.11] Docs: Normalise Argument Clinic advanced topics headings (GH-106842) (#106852)
erlend-aasland
webhook-mailer at python.org
Tue Jul 18 06:25:28 EDT 2023
https://github.com/python/cpython/commit/38553442c88c331d91562b77f023345e0b33b5f9
commit: 38553442c88c331d91562b77f023345e0b33b5f9
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-07-18T12:25:25+02:00
summary:
[3.11] Docs: Normalise Argument Clinic advanced topics headings (GH-106842) (#106852)
(cherry picked from commit 4cb0b9c0a9f6a4154238c98013d2679229b1f794)
Co-authored-by: Erlend E. Aasland <erlend at python.org>
Co-authored-by: Ezio Melotti <ezio.melotti at gmail.com>
files:
M Doc/howto/clinic.rst
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 70b3e21d81a61..287a4acebb133 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -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:
@@ -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
@@ -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
@@ -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
@@ -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
@@ -892,8 +889,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),
@@ -901,8 +898,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.
@@ -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:
@@ -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
@@ -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
@@ -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>`.
@@ -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,
@@ -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
@@ -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``
@@ -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
@@ -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``.
@@ -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
@@ -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
@@ -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:
@@ -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:
@@ -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
@@ -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
More information about the Python-checkins
mailing list