[3.11] Docs: Normalize Argument Clinic How-To section capitalization (GH-106788) (#106792)

(cherry picked from commit 8c17729489)

Co-authored-by: Erlend E. Aasland <erlend@python.org>
This commit is contained in:
Miss Islington (bot) 2023-07-15 15:50:43 -07:00 committed by GitHub
parent 465f5b09df
commit c73f9c045e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 18 additions and 11 deletions

View File

@ -27,7 +27,8 @@ Argument Clinic How-To
version of Argument Clinic that ships with the next version
of CPython *could* be totally incompatible and break all your code.
The Goals Of Argument Clinic
The goals of Argument Clinic
============================
Argument Clinic's primary goal
@ -78,7 +79,7 @@ and it should be able to do many interesting and smart
things with all the information you give it.
Basic Concepts And Usage
Basic concepts and usage
========================
Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py``.
@ -141,7 +142,7 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic:
a block.)
Converting Your First Function
Converting your first function
==============================
The best way to get a sense of how Argument Clinic works is to
@ -550,7 +551,8 @@ Let's dive in!
Congratulations, you've ported your first function to work with Argument Clinic!
Advanced Topics
Advanced topics
===============
Now that you've had some experience working with Argument Clinic, it's time
@ -628,7 +630,8 @@ after the last argument).
Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this
will change soon.
Optional Groups
Optional groups
---------------
Some legacy functions have a tricky approach to parsing their arguments:
@ -888,6 +891,7 @@ available. For each converter it'll show you all the parameters
it accepts, along with the default value for each parameter.
Just run ``Tools/clinic/clinic.py --converters`` to see the full list.
Py_buffer
---------
@ -897,7 +901,6 @@ 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
-------------------
@ -964,6 +967,7 @@ value called ``NULL`` for just this reason: from Python's perspective it
behaves like a default value of ``None``, but the C variable is initialized
with ``NULL``.
Expressions specified as default values
---------------------------------------
@ -1021,7 +1025,6 @@ you're not permitted to use:
* Tuple/list/set/dict literals.
Using a return converter
------------------------
@ -1140,6 +1143,7 @@ then modifying it. Cloning is an all-or nothing proposition.
Also, the function you are cloning from must have been previously defined
in the current file.
Calling Python code
-------------------
@ -1374,6 +1378,7 @@ handle initialization and cleanup.
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
---------------------------------
@ -1388,8 +1393,9 @@ write your own return converter, please read ``Tools/clinic/clinic.py``,
specifically the implementation of ``CReturnConverter`` and
all its subclasses.
METH_O and METH_NOARGS
----------------------------------------------
----------------------
To convert a function using ``METH_O``, make sure the function's
single argument is using the ``object`` converter, and mark the
@ -1409,8 +1415,9 @@ any arguments.
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
----------------------------------------------
----------------------------
You can convert ``tp_new`` and ``tp_init`` functions. Just name
them ``__new__`` or ``__init__`` as appropriate. Notes:
@ -1431,6 +1438,7 @@ them ``__new__`` or ``__init__`` as appropriate. Notes:
(If your function doesn't support keywords, the parsing function
generated will throw an exception if it receives any.)
Changing and redirecting Clinic's output
----------------------------------------
@ -1715,7 +1723,7 @@ the file was not modified by hand before it gets overwritten.
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
@ -1795,7 +1803,6 @@ 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
-------------------------------------