mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-02 13:22:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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

Browse source 
(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
Download patch file Download diff file Expand all files Collapse all files

29
Doc/howto/clinic.rst
View file

@ -27,7 +27,8 @@ Argument Clinic How-To
version of Argument Clinic that ships with the next version version of Argument Clinic that ships with the next version
of CPython *could* be totally incompatible and break all your code. 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 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. 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``. 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.) a block.)
Converting Your First Function Converting your first function
============================== ==============================
The best way to get a sense of how Argument Clinic works is to 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! 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 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 Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this
will change soon. will change soon.
Optional Groups
Optional groups
--------------- ---------------
Some legacy functions have a tricky approach to parsing their arguments: 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. 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 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). Argument Clinic generates code that does it for you (in the parsing function).
Advanced converters 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 behaves like a default value of ``None``, but the C variable is initialized
with ``NULL``. with ``NULL``.
Expressions specified as default values Expressions specified as default values
--------------------------------------- ---------------------------------------
@ -1021,7 +1025,6 @@ you're not permitted to use:
* Tuple/list/set/dict literals. * Tuple/list/set/dict literals.
Using a return converter 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 Also, the function you are cloning from must have been previously defined
in the current file. in the current file.
Calling Python code Calling Python code
------------------- -------------------
@ -1374,6 +1378,7 @@ handle initialization and cleanup.
You can see more examples of custom converters in the CPython 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 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 specifically the implementation of ``CReturnConverter`` and
all its subclasses. all its subclasses.
METH_O and METH_NOARGS METH_O and METH_NOARGS
---------------------------------------------- ----------------------
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
@ -1409,8 +1415,9 @@ any arguments.
You can still use a self converter, a return converter, and specify 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 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:
@ -1431,6 +1438,7 @@ them ``__new__`` or ``__init__`` as appropriate. Notes:
(If your function doesn't support keywords, the parsing function (If your function doesn't support keywords, the parsing function
generated will throw an exception if it receives any.) generated will throw an exception if it receives any.)
Changing and redirecting Clinic's output Changing and redirecting Clinic's output
---------------------------------------- ----------------------------------------
@ -1715,7 +1723,7 @@ the file was not modified by hand before it gets overwritten.
The #ifdef trick 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
@ -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. move it above the ``PyMethodDef`` structure where that macro is used.
Using Argument Clinic in Python files Using Argument Clinic in Python files
------------------------------------- -------------------------------------