mirror of https://github.com/python/cpython.git
[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:
parent
465f5b09df
commit
c73f9c045e
|
@ -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
|
||||
-------------------------------------
|
||||
|
||||
|
|
Loading…
Reference in New Issue