mirror of https://github.com/python/cpython
Docs: Add missing markup to Argument Clinic docs (#106876)
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
This commit is contained in:
Erlend E. Aasland
GitHub
parent
7516953275
commit
ff5f94b72c
|
|
@ -96,7 +96,8 @@ things with all the information you give it.
|
|||
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
|
||||
:source:`Tools/clinic/clinic.py`.
|
||||
If you run that script, specifying a C file as an argument:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
|
@ -178,9 +179,10 @@ Let's dive in!
|
|||
1. Find a Python builtin that calls either :c:func:`PyArg_ParseTuple`
|
||||
or :c:func:`PyArg_ParseTupleAndKeywords`, and hasn't been converted
|
||||
to work with Argument Clinic yet.
|
||||
For my example I'm using ``_pickle.Pickler.dump()``.
|
||||
For my example I'm using
|
||||
:py:meth:`_pickle.Pickler.dump <pickle.Pickler.dump>`.
|
||||
|
||||
2. If the call to the ``PyArg_Parse`` function uses any of the
|
||||
2. If the call to the :c:func:`!PyArg_Parse*` function uses any of the
|
||||
following format units:
|
||||
|
||||
.. code-block:: none
|
||||
|
|
@ -197,10 +199,10 @@ Let's dive in!
|
|||
support all of these scenarios. But these are advanced
|
||||
topics—let's do something simpler for your first function.
|
||||
|
||||
Also, if the function has multiple calls to :c:func:`PyArg_ParseTuple`
|
||||
Also, if the function has multiple calls to :c:func:`!PyArg_ParseTuple`
|
||||
or :c:func:`PyArg_ParseTupleAndKeywords` where it supports different
|
||||
types for the same argument, or if the function uses something besides
|
||||
PyArg_Parse functions to parse its arguments, it probably
|
||||
:c:func:`!PyArg_Parse*` functions to parse its arguments, it probably
|
||||
isn't suitable for conversion to Argument Clinic. Argument Clinic
|
||||
doesn't support generic functions or polymorphic parameters.
|
||||
|
||||
|
|
@ -217,7 +219,7 @@ Let's dive in!
|
|||
|
||||
If the old docstring had a first line that looked like a function
|
||||
signature, throw that line away. (The docstring doesn't need it
|
||||
anymore—when you use ``help()`` on your builtin in the future,
|
||||
anymore—when you use :py:func:`help` on your builtin in the future,
|
||||
the first line will be built automatically based on the function's
|
||||
signature.)
|
||||
|
||||
|
|
@ -264,7 +266,7 @@ Let's dive in!
|
|||
|
||||
When you declare a class, you must also specify two aspects of its type
|
||||
in C: the type declaration you'd use for a pointer to an instance of
|
||||
this class, and a pointer to the :c:type:`PyTypeObject` for this class.
|
||||
this class, and a pointer to the :c:type:`!PyTypeObject` for this class.
|
||||
|
||||
Sample::
|
||||
|
||||
|
|
@ -313,10 +315,10 @@ Let's dive in!
|
|||
Clinic easier.
|
||||
|
||||
For each parameter, copy the "format unit" for that
|
||||
parameter from the ``PyArg_Parse()`` format argument and
|
||||
parameter from the :c:func:`PyArg_Parse` format argument and
|
||||
specify *that* as its converter, as a quoted
|
||||
string. ("format unit" is the formal name for the one-to-three
|
||||
character substring of the ``format`` parameter that tells
|
||||
character substring of the *format* parameter that tells
|
||||
the argument parsing function what the type of the variable
|
||||
is and how to convert it. For more on format units please
|
||||
see :ref:`arg-parsing`.)
|
||||
|
|
@ -349,7 +351,7 @@ Let's dive in!
|
|||
itself before the first keyword-only argument, indented the
|
||||
same as the parameter lines.
|
||||
|
||||
(``_pickle.Pickler.dump`` has neither, so our sample is unchanged.)
|
||||
(:py:meth:`!_pickle.Pickler.dump` has neither, so our sample is unchanged.)
|
||||
|
||||
|
||||
10. If the existing C function calls :c:func:`PyArg_ParseTuple`
|
||||
|
|
@ -410,7 +412,7 @@ Let's dive in!
|
|||
|
||||
12. Save and close the file, then run ``Tools/clinic/clinic.py`` on
|
||||
it. With luck everything worked---your block now has output, and
|
||||
a ``.c.h`` file has been generated! Reopen the file in your
|
||||
a :file:`.c.h` file has been generated! Reopen the file in your
|
||||
text editor to see::
|
||||
|
||||
/*[clinic input]
|
||||
|
|
@ -431,8 +433,8 @@ Let's dive in!
|
|||
it found an error in your input. Keep fixing your errors and retrying
|
||||
until Argument Clinic processes your file without complaint.
|
||||
|
||||
For readability, most of the glue code has been generated to a ``.c.h``
|
||||
file. You'll need to include that in your original ``.c`` file,
|
||||
For readability, most of the glue code has been generated to a :file:`.c.h`
|
||||
file. You'll need to include that in your original :file:`.c` file,
|
||||
typically right after the clinic module block::
|
||||
|
||||
#include "clinic/_pickle.c.h"
|
||||
|
|
@ -446,8 +448,8 @@ Let's dive in!
|
|||
ensure that the code generated by Argument Clinic calls the
|
||||
*exact* same function.
|
||||
|
||||
Second, the format string passed in to :c:func:`PyArg_ParseTuple` or
|
||||
:c:func:`PyArg_ParseTupleAndKeywords` should be *exactly* the same
|
||||
Second, the format string passed in to :c:func:`!PyArg_ParseTuple` or
|
||||
:c:func:`!PyArg_ParseTupleAndKeywords` should be *exactly* the same
|
||||
as the hand-written one in the existing function, up to the colon
|
||||
or semi-colon.
|
||||
|
||||
|
|
@ -469,7 +471,7 @@ Let's dive in!
|
|||
{"dump", (PyCFunction)__pickle_Pickler_dump, METH_O, __pickle_Pickler_dump__doc__},
|
||||
|
||||
This static structure should be *exactly* the same as the existing static
|
||||
:c:type:`PyMethodDef` structure for this builtin.
|
||||
:c:type:`!PyMethodDef` structure for this builtin.
|
||||
|
||||
If any of these items differ in *any way*,
|
||||
adjust your Argument Clinic function specification and rerun
|
||||
|
|
@ -539,14 +541,14 @@ Let's dive in!
|
|||
...
|
||||
|
||||
15. Remember the macro with the :c:type:`PyMethodDef` structure for this
|
||||
function? Find the existing :c:type:`PyMethodDef` structure for this
|
||||
function? Find the existing :c:type:`!PyMethodDef` structure for this
|
||||
function and replace it with a reference to the macro. (If the builtin
|
||||
is at module scope, this will probably be very near the end of the file;
|
||||
if the builtin is a class method, this will probably be below but relatively
|
||||
near to the implementation.)
|
||||
|
||||
Note that the body of the macro contains a trailing comma. So when you
|
||||
replace the existing static :c:type:`PyMethodDef` structure with the macro,
|
||||
replace the existing static :c:type:`!PyMethodDef` structure with the macro,
|
||||
*don't* add a comma to the end.
|
||||
|
||||
Sample::
|
||||
|
|
@ -562,7 +564,7 @@ Let's dive in!
|
|||
|
||||
&_Py_ID(new_unique_py_id)
|
||||
|
||||
If it does, you'll have to run ``Tools/scripts/generate_global_objects.py``
|
||||
If it does, you'll have to run ``make regen-global-objects``
|
||||
to regenerate the list of precompiled identifiers at this point.
|
||||
|
||||
|
||||
|
|
@ -570,7 +572,7 @@ Let's dive in!
|
|||
This change should not introduce any new compile-time warnings or errors,
|
||||
and there should be no externally visible change to Python's behavior.
|
||||
|
||||
Well, except for one difference: ``inspect.signature()`` run on your function
|
||||
Well, except for one difference: :py:func:`inspect.signature` run on your function
|
||||
should now provide a valid signature!
|
||||
|
||||
Congratulations, you've ported your first function to work with Argument Clinic!
|
||||
|
|
@ -594,15 +596,15 @@ Argument Clinic will use that function name for the base (generated) function,
|
|||
then add ``"_impl"`` to the end and use that for the name of the impl function.
|
||||
|
||||
For example, if we wanted to rename the C function names generated for
|
||||
``pickle.Pickler.dump``, it'd look like this::
|
||||
:py:meth:`pickle.Pickler.dump`, it'd look like this::
|
||||
|
||||
/*[clinic input]
|
||||
pickle.Pickler.dump as pickler_dumper
|
||||
|
||||
...
|
||||
|
||||
The base function would now be named ``pickler_dumper()``,
|
||||
and the impl function would now be named ``pickler_dumper_impl()``.
|
||||
The base function would now be named :c:func:`!pickler_dumper`,
|
||||
and the impl function would now be named :c:func:`!pickler_dumper_impl`.
|
||||
|
||||
|
||||
Similarly, you may have a problem where you want to give a parameter
|
||||
|
|
@ -620,9 +622,9 @@ using the same ``"as"`` syntax::
|
|||
fix_imports: bool = True
|
||||
|
||||
Here, the name used in Python (in the signature and the ``keywords``
|
||||
array) would be ``file``, but the C variable would be named ``file_obj``.
|
||||
array) would be *file*, but the C variable would be named ``file_obj``.
|
||||
|
||||
You can use this to rename the ``self`` parameter too!
|
||||
You can use this to rename the *self* parameter too!
|
||||
|
||||
|
||||
How to convert functions using ``PyArg_UnpackTuple``
|
||||
|
|
@ -630,7 +632,7 @@ 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
|
||||
may specify the ``type`` argument to cast the type as appropriate. All
|
||||
may specify the *type* argument to cast the type as appropriate. All
|
||||
arguments should be marked positional-only (add a ``/`` on a line by itself
|
||||
after the last argument).
|
||||
|
||||
|
|
@ -649,16 +651,16 @@ keyword-only arguments.) This approach was used to simulate optional
|
|||
arguments back before :c:func:`PyArg_ParseTupleAndKeywords` was created.
|
||||
|
||||
While functions using this approach can often be converted to
|
||||
use :c:func:`PyArg_ParseTupleAndKeywords`, optional arguments, and default values,
|
||||
use :c:func:`!PyArg_ParseTupleAndKeywords`, optional arguments, and default values,
|
||||
it's not always possible. Some of these legacy functions have
|
||||
behaviors :c:func:`PyArg_ParseTupleAndKeywords` doesn't directly support.
|
||||
The most obvious example is the builtin function ``range()``, which has
|
||||
behaviors :c:func:`!PyArg_ParseTupleAndKeywords` doesn't directly support.
|
||||
The most obvious example is the builtin function :py:func:`range`, which has
|
||||
an optional argument on the *left* side of its required argument!
|
||||
Another example is ``curses.window.addch()``, which has a group of two
|
||||
Another example is :py:meth:`curses.window.addch`, which has a group of two
|
||||
arguments that must always be specified together. (The arguments are
|
||||
called ``x`` and ``y``; if you call the function passing in ``x``,
|
||||
you must also pass in ``y``—and if you don't pass in ``x`` you may not
|
||||
pass in ``y`` either.)
|
||||
called *x* and *y*; if you call the function passing in *x*,
|
||||
you must also pass in *y* — and if you don't pass in *x* you may not
|
||||
pass in *y* either.)
|
||||
|
||||
In any case, the goal of Argument Clinic is to support argument parsing
|
||||
for all existing CPython builtins without changing their semantics.
|
||||
|
|
@ -679,7 +681,7 @@ can *only* be used with positional-only parameters.
|
|||
|
||||
To specify an optional group, add a ``[`` on a line by itself before
|
||||
the parameters you wish to group together, and a ``]`` on a line by itself
|
||||
after these parameters. As an example, here's how ``curses.window.addch``
|
||||
after these parameters. As an example, here's how :py:meth:`curses.window.addch`
|
||||
uses optional groups to make the first two parameters and the last
|
||||
parameter optional::
|
||||
|
||||
|
|
@ -765,25 +767,25 @@ the same converters.
|
|||
All arguments to Argument Clinic converters are keyword-only.
|
||||
All Argument Clinic converters accept the following arguments:
|
||||
|
||||
``c_default``
|
||||
*c_default*
|
||||
The default value for this parameter when defined in C.
|
||||
Specifically, this will be the initializer for the variable declared
|
||||
in the "parse function". See :ref:`the section on default values <default_values>`
|
||||
for how to use this.
|
||||
Specified as a string.
|
||||
|
||||
``annotation``
|
||||
*annotation*
|
||||
The annotation value for this parameter. Not currently supported,
|
||||
because :pep:`8` mandates that the Python library may not use
|
||||
annotations.
|
||||
|
||||
``unused``
|
||||
*unused*
|
||||
Wrap the argument with :c:macro:`Py_UNUSED` in the impl function signature.
|
||||
|
||||
In addition, some converters accept additional arguments. Here is a list
|
||||
of these arguments, along with their meanings:
|
||||
|
||||
``accept``
|
||||
*accept*
|
||||
A set of Python types (and possibly pseudo-types);
|
||||
this restricts the allowable Python argument to values of these types.
|
||||
(This is not a general-purpose facility; as a rule it only supports
|
||||
|
|
@ -791,38 +793,38 @@ of these arguments, along with their meanings:
|
|||
|
||||
To accept ``None``, add ``NoneType`` to this set.
|
||||
|
||||
``bitwise``
|
||||
*bitwise*
|
||||
Only supported for unsigned integers. The native integer value of this
|
||||
Python argument will be written to the parameter without any range checking,
|
||||
even for negative values.
|
||||
|
||||
``converter``
|
||||
*converter*
|
||||
Only supported by the ``object`` converter. Specifies the name of a
|
||||
:ref:`C "converter function" <o_ampersand>`
|
||||
to use to convert this object to a native type.
|
||||
|
||||
``encoding``
|
||||
*encoding*
|
||||
Only supported for strings. Specifies the encoding to use when converting
|
||||
this string from a Python str (Unicode) value into a C ``char *`` value.
|
||||
|
||||
|
||||
``subclass_of``
|
||||
*subclass_of*
|
||||
Only supported for the ``object`` converter. Requires that the Python
|
||||
value be a subclass of a Python type, as expressed in C.
|
||||
|
||||
``type``
|
||||
*type*
|
||||
Only supported for the ``object`` and ``self`` converters. Specifies
|
||||
the C type that will be used to declare the variable. Default value is
|
||||
``"PyObject *"``.
|
||||
|
||||
``zeroes``
|
||||
*zeroes*
|
||||
Only supported for strings. If true, embedded NUL bytes (``'\\0'``) are
|
||||
permitted inside the value. The length of the string will be passed in
|
||||
to the impl function, just after the string parameter, as a parameter named
|
||||
``<parameter_name>_length``.
|
||||
|
||||
Please note, not every possible combination of arguments will work.
|
||||
Usually these arguments are implemented by specific ``PyArg_ParseTuple``
|
||||
Usually these arguments are implemented by specific :c:func:`PyArg_ParseTuple`
|
||||
*format units*, with specific behavior. For example, currently you cannot
|
||||
call ``unsigned_short`` without also specifying ``bitwise=True``.
|
||||
Although it's perfectly reasonable to think this would work, these semantics don't
|
||||
|
|
@ -922,19 +924,19 @@ conversion functions, or types, or strings specifying an encoding.
|
|||
(But "legacy converters" don't support arguments. That's why we
|
||||
skipped them for your first function.) The argument you specified
|
||||
to the format unit is now an argument to the converter; this
|
||||
argument is either ``converter`` (for ``O&``), ``subclass_of`` (for ``O!``),
|
||||
or ``encoding`` (for all the format units that start with ``e``).
|
||||
argument is either *converter* (for ``O&``), *subclass_of* (for ``O!``),
|
||||
or *encoding* (for all the format units that start with ``e``).
|
||||
|
||||
When using ``subclass_of``, you may also want to use the other
|
||||
custom argument for ``object()``: ``type``, which lets you set the type
|
||||
When using *subclass_of*, you may also want to use the other
|
||||
custom argument for ``object()``: *type*, which lets you set the type
|
||||
actually used for the parameter. For example, if you want to ensure
|
||||
that the object is a subclass of ``PyUnicode_Type``, you probably want
|
||||
that the object is a subclass of :c:var:`PyUnicode_Type`, you probably want
|
||||
to use the converter ``object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type')``.
|
||||
|
||||
One possible problem with using Argument Clinic: it takes away some possible
|
||||
flexibility for the format units starting with ``e``. When writing a
|
||||
``PyArg_Parse`` call by hand, you could theoretically decide at runtime what
|
||||
encoding string to pass in to :c:func:`PyArg_ParseTuple`. But now this string must
|
||||
:c:func:`!PyArg_Parse*` call by hand, you could theoretically decide at runtime what
|
||||
encoding string to pass to that call. But now this string must
|
||||
be hard-coded at Argument-Clinic-preprocessing-time. This limitation is deliberate;
|
||||
it made supporting this format unit much easier, and may allow for future optimizations.
|
||||
This restriction doesn't seem unreasonable; CPython itself always passes in static
|
||||
|
|
@ -987,7 +989,7 @@ expression. Currently the following are explicitly supported:
|
|||
* Numeric constants (integer and float)
|
||||
* String constants
|
||||
* ``True``, ``False``, and ``None``
|
||||
* Simple symbolic constants like ``sys.maxsize``, which must
|
||||
* Simple symbolic constants like :py:data:`sys.maxsize`, which must
|
||||
start with the name of the module
|
||||
|
||||
(In the future, this may need to get even more elaborate,
|
||||
|
|
@ -1008,28 +1010,28 @@ Consider the following example:
|
|||
|
||||
foo: Py_ssize_t = sys.maxsize - 1
|
||||
|
||||
``sys.maxsize`` can have different values on different platforms. Therefore
|
||||
:py:data:`sys.maxsize` can have different values on different platforms. Therefore
|
||||
Argument Clinic can't simply evaluate that expression locally and hard-code it
|
||||
in C. So it stores the default in such a way that it will get evaluated at
|
||||
runtime, when the user asks for the function's signature.
|
||||
|
||||
What namespace is available when the expression is evaluated? It's evaluated
|
||||
in the context of the module the builtin came from. So, if your module has an
|
||||
attribute called "``max_widgets``", you may simply use it:
|
||||
attribute called :py:attr:`!max_widgets`, you may simply use it:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
foo: Py_ssize_t = max_widgets
|
||||
|
||||
If the symbol isn't found in the current module, it fails over to looking in
|
||||
``sys.modules``. That's how it can find ``sys.maxsize`` for example. (Since you
|
||||
don't know in advance what modules the user will load into their interpreter,
|
||||
:py:data:`sys.modules`. That's how it can find :py:data:`sys.maxsize` for example.
|
||||
(Since you don't know in advance what modules the user will load into their interpreter,
|
||||
it's best to restrict yourself to modules that are preloaded by Python itself.)
|
||||
|
||||
Evaluating default values only at runtime means Argument Clinic can't compute
|
||||
the correct equivalent C default value. So you need to tell it explicitly.
|
||||
When you use an expression, you must also specify the equivalent expression
|
||||
in C, using the ``c_default`` parameter to the converter:
|
||||
in C, using the *c_default* parameter to the converter:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
|
@ -1095,7 +1097,7 @@ indicate an error has occurred? Normally, a function returns a valid (non-``NUL
|
|||
pointer for success, and ``NULL`` for failure. But if you use an integer return converter,
|
||||
all integers are valid. How can Argument Clinic detect an error? Its solution: each return
|
||||
converter implicitly looks for a special value that indicates an error. If you return
|
||||
that value, and an error has been set (``PyErr_Occurred()`` returns a true
|
||||
that value, and an error has been set (c:func:`PyErr_Occurred` returns a true
|
||||
value), then the generated code will propagate the error. Otherwise it will
|
||||
encode the value you return like normal.
|
||||
|
||||
|
|
@ -1201,9 +1203,9 @@ using a default converter. It automatically sets the ``type``
|
|||
of this parameter to the "pointer to an instance" you specified
|
||||
when you declared the type. However, you can override
|
||||
Argument Clinic's converter and specify one yourself.
|
||||
Just add your own ``self`` parameter as the first parameter in a
|
||||
Just add your own *self* parameter as the first parameter in a
|
||||
block, and ensure that its converter is an instance of
|
||||
``self_converter`` or a subclass thereof.
|
||||
:class:`!self_converter` or a subclass thereof.
|
||||
|
||||
What's the point? This lets you override the type of ``self``,
|
||||
or give it a different default name.
|
||||
|
|
@ -1211,7 +1213,7 @@ or give it a different default name.
|
|||
How do you specify the custom type you want to cast ``self`` to?
|
||||
If you only have one or two functions with the same type for ``self``,
|
||||
you can directly use Argument Clinic's existing ``self`` converter,
|
||||
passing in the type you want to use as the ``type`` parameter::
|
||||
passing in the type you want to use as the *type* parameter::
|
||||
|
||||
/*[clinic input]
|
||||
|
||||
|
|
@ -1226,7 +1228,7 @@ passing in the type you want to use as the ``type`` parameter::
|
|||
|
||||
On the other hand, if you have a lot of functions that will use the same
|
||||
type for ``self``, it's best to create your own converter, subclassing
|
||||
``self_converter`` but overwriting the ``type`` member::
|
||||
:class:`!self_converter` but overwriting the :py:attr:`!type` member::
|
||||
|
||||
/*[python input]
|
||||
class PicklerObject_converter(self_converter):
|
||||
|
|
@ -1254,8 +1256,8 @@ module level state. Use :c:func:`PyType_FromModuleAndSpec` to associate a new
|
|||
heap type with a module. You can now use :c:func:`PyType_GetModuleState` on
|
||||
the defining class to fetch the module state, for example from a module method.
|
||||
|
||||
Example from ``Modules/zlibmodule.c``. First, ``defining_class`` is added to
|
||||
the clinic input::
|
||||
Example from :source:`Modules/zlibmodule.c`.
|
||||
First, ``defining_class`` is added to the clinic input::
|
||||
|
||||
/*[clinic input]
|
||||
zlib.Compress.compress
|
||||
|
|
@ -1285,16 +1287,17 @@ module state::
|
|||
Each method may only have one argument using this converter, and it must appear
|
||||
after ``self``, or, if ``self`` is not used, as the first argument. The argument
|
||||
will be of type ``PyTypeObject *``. The argument will not appear in the
|
||||
``__text_signature__``.
|
||||
:py:attr:`!__text_signature__`.
|
||||
|
||||
The ``defining_class`` converter is not compatible with ``__init__`` and ``__new__``
|
||||
methods, which cannot use the ``METH_METHOD`` convention.
|
||||
The ``defining_class`` converter is not compatible with :py:meth:`!__init__`
|
||||
and :py:meth:`!__new__` methods, which cannot use the :c:macro:`METH_METHOD`
|
||||
convention.
|
||||
|
||||
It is not possible to use ``defining_class`` with slot methods. In order to
|
||||
fetch the module state from such methods, use :c:func:`PyType_GetModuleByDef`
|
||||
to look up the module and then :c:func:`PyModule_GetState` to fetch the module
|
||||
state. Example from the ``setattro`` slot method in
|
||||
``Modules/_threadmodule.c``::
|
||||
:source:`Modules/_threadmodule.c`::
|
||||
|
||||
static int
|
||||
local_setattro(localobject *self, PyObject *name, PyObject *v)
|
||||
|
|
@ -1312,7 +1315,7 @@ 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``.
|
||||
A converter is simply a Python class that inherits from :py:class:`!CConverter`.
|
||||
The main purpose of a custom converter is if you have a parameter using
|
||||
the ``O&`` format unit—parsing this parameter means calling
|
||||
a :c:func:`PyArg_ParseTuple` "converter function".
|
||||
|
|
@ -1323,61 +1326,74 @@ will be automatically registered with Argument Clinic; its name
|
|||
will be the name of your class with the ``_converter`` suffix
|
||||
stripped off. (This is accomplished with a metaclass.)
|
||||
|
||||
You shouldn't subclass ``CConverter.__init__``. Instead, you should
|
||||
write a ``converter_init()`` function. ``converter_init()``
|
||||
always accepts a ``self`` parameter; after that, all additional
|
||||
You shouldn't subclass :py:meth:`!CConverter.__init__`. Instead, you should
|
||||
write a :py:meth:`!converter_init` function. :py:meth:`!converter_init`
|
||||
always accepts a *self* parameter; after that, all additional
|
||||
parameters *must* be keyword-only. Any arguments passed in to
|
||||
the converter in Argument Clinic will be passed along to your
|
||||
``converter_init()``.
|
||||
:py:meth:`!converter_init`.
|
||||
|
||||
There are some additional members of ``CConverter`` you may wish
|
||||
There are some additional members of :py:class:`!CConverter` you may wish
|
||||
to specify in your subclass. Here's the current list:
|
||||
|
||||
``type``
|
||||
The C type to use for this variable.
|
||||
``type`` should be a Python string specifying the type, e.g. ``int``.
|
||||
If this is a pointer type, the type string should end with ``' *'``.
|
||||
.. module:: clinic
|
||||
|
||||
``default``
|
||||
The Python default value for this parameter, as a Python value.
|
||||
Or the magic value ``unspecified`` if there is no default.
|
||||
.. class:: CConverter
|
||||
|
||||
``py_default``
|
||||
``default`` as it should appear in Python code,
|
||||
as a string.
|
||||
Or ``None`` if there is no default.
|
||||
.. attribute:: type
|
||||
|
||||
``c_default``
|
||||
``default`` as it should appear in C code,
|
||||
as a string.
|
||||
Or ``None`` if there is no default.
|
||||
The C type to use for this variable.
|
||||
:attr:`!type` should be a Python string specifying the type,
|
||||
e.g. ``'int'``.
|
||||
If this is a pointer type, the type string should end with ``' *'``.
|
||||
|
||||
``c_ignored_default``
|
||||
The default value used to initialize the C variable when
|
||||
there is no default, but not specifying a default may
|
||||
result in an "uninitialized variable" warning. This can
|
||||
easily happen when using option groups—although
|
||||
properly written code will never actually use this value,
|
||||
the variable does get passed in to the impl, and the
|
||||
C compiler will complain about the "use" of the
|
||||
uninitialized value. This value should always be a
|
||||
non-empty string.
|
||||
.. attribute:: default
|
||||
|
||||
``converter``
|
||||
The name of the C converter function, as a string.
|
||||
The Python default value for this parameter, as a Python value.
|
||||
Or the magic value ``unspecified`` if there is no default.
|
||||
|
||||
``impl_by_reference``
|
||||
A boolean value. If true,
|
||||
Argument Clinic will add a ``&`` in front of the name of
|
||||
the variable when passing it into the impl function.
|
||||
.. attribute:: py_default
|
||||
|
||||
``parse_by_reference``
|
||||
A boolean value. If true,
|
||||
Argument Clinic will add a ``&`` in front of the name of
|
||||
the variable when passing it into :c:func:`PyArg_ParseTuple`.
|
||||
:attr:`!default` as it should appear in Python code,
|
||||
as a string.
|
||||
Or ``None`` if there is no default.
|
||||
|
||||
.. attribute:: c_default
|
||||
|
||||
:attr:`!default` as it should appear in C code,
|
||||
as a string.
|
||||
Or ``None`` if there is no default.
|
||||
|
||||
.. attribute:: c_ignored_default
|
||||
|
||||
The default value used to initialize the C variable when
|
||||
there is no default, but not specifying a default may
|
||||
result in an "uninitialized variable" warning. This can
|
||||
easily happen when using option groups—although
|
||||
properly written code will never actually use this value,
|
||||
the variable does get passed in to the impl, and the
|
||||
C compiler will complain about the "use" of the
|
||||
uninitialized value. This value should always be a
|
||||
non-empty string.
|
||||
|
||||
.. attribute:: converter
|
||||
|
||||
The name of the C converter function, as a string.
|
||||
|
||||
.. attribute:: impl_by_reference
|
||||
|
||||
A boolean value. If true,
|
||||
Argument Clinic will add a ``&`` in front of the name of
|
||||
the variable when passing it into the impl function.
|
||||
|
||||
.. attribute:: parse_by_reference
|
||||
|
||||
A boolean value. If true,
|
||||
Argument Clinic will add a ``&`` in front of the name of
|
||||
the variable when passing it into :c:func:`PyArg_ParseTuple`.
|
||||
|
||||
|
||||
Here's the simplest example of a custom converter, from ``Modules/zlibmodule.c``::
|
||||
Here's the simplest example of a custom converter, from :source:`Modules/zlibmodule.c`::
|
||||
|
||||
/*[python input]
|
||||
|
||||
|
|
@ -1397,7 +1413,7 @@ automatically support default values.
|
|||
More sophisticated custom converters can insert custom C code to
|
||||
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``.
|
||||
source tree; grep the C files for the string :py:class:`!CConverter`.
|
||||
|
||||
|
||||
How to write a custom return converter
|
||||
|
|
@ -1407,18 +1423,18 @@ Writing a custom return converter is much like writing
|
|||
a custom converter. Except it's somewhat simpler, because return
|
||||
converters are themselves much simpler.
|
||||
|
||||
Return converters must subclass ``CReturnConverter``.
|
||||
Return converters must subclass :py:class:`!CReturnConverter`.
|
||||
There are no examples yet of custom return converters,
|
||||
because they are not widely used yet. If you wish to
|
||||
write your own return converter, please read ``Tools/clinic/clinic.py``,
|
||||
specifically the implementation of ``CReturnConverter`` and
|
||||
write your own return converter, please read :source:`Tools/clinic/clinic.py`,
|
||||
specifically the implementation of :py:class:`!CReturnConverter` and
|
||||
all its subclasses.
|
||||
|
||||
|
||||
How to convert ``METH_O`` and ``METH_NOARGS`` functions
|
||||
-------------------------------------------------------
|
||||
|
||||
To convert a function using ``METH_O``, make sure the function's
|
||||
To convert a function using :c:macro:`METH_O`, make sure the function's
|
||||
single argument is using the ``object`` converter, and mark the
|
||||
arguments as positional-only::
|
||||
|
||||
|
|
@ -1430,24 +1446,25 @@ arguments as positional-only::
|
|||
[clinic start generated code]*/
|
||||
|
||||
|
||||
To convert a function using ``METH_NOARGS``, just don't specify
|
||||
To convert a function using :c:macro:`METH_NOARGS`, just don't specify
|
||||
any arguments.
|
||||
|
||||
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 :c:macro:`METH_O`.
|
||||
|
||||
|
||||
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:
|
||||
You can convert :c:member:`~PyTypeObject.tp_new` and
|
||||
:c:member:`~PyTypeObject.tp_init` functions.
|
||||
Just name them ``__new__`` or ``__init__`` as appropriate. Notes:
|
||||
|
||||
* The function name generated for ``__new__`` doesn't end in ``__new__``
|
||||
like it would by default. It's just the name of the class, converted
|
||||
into a valid C identifier.
|
||||
|
||||
* No ``PyMethodDef`` ``#define`` is generated for these functions.
|
||||
* No :c:type:`PyMethodDef` ``#define`` is generated for these functions.
|
||||
|
||||
* ``__init__`` functions return ``int``, not ``PyObject *``.
|
||||
|
||||
|
|
@ -1482,7 +1499,7 @@ Let's start with defining some terminology:
|
|||
|
||||
*field*
|
||||
A field, in this context, is a subsection of Clinic's output.
|
||||
For example, the ``#define`` for the ``PyMethodDef`` structure
|
||||
For example, the ``#define`` for the :c:type:`PyMethodDef` structure
|
||||
is a field, called ``methoddef_define``. Clinic has seven
|
||||
different fields it can output per function definition:
|
||||
|
||||
|
|
@ -1526,8 +1543,8 @@ Let's start with defining some terminology:
|
|||
The filename chosen for the file is ``{basename}.clinic{extension}``,
|
||||
where ``basename`` and ``extension`` were assigned the output
|
||||
from ``os.path.splitext()`` run on the current file. (Example:
|
||||
the ``file`` destination for ``_pickle.c`` would be written to
|
||||
``_pickle.clinic.c``.)
|
||||
the ``file`` destination for :file:`_pickle.c` would be written to
|
||||
:file:`_pickle.clinic.c`.)
|
||||
|
||||
**Important: When using a** ``file`` **destination, you**
|
||||
*must check in* **the generated file!**
|
||||
|
|
@ -1780,7 +1797,7 @@ like so::
|
|||
}
|
||||
#endif /* HAVE_FUNCTIONNAME */
|
||||
|
||||
Then, remove those three lines from the ``PyMethodDef`` structure,
|
||||
Then, remove those three lines from the :c:type:`PyMethodDef` structure,
|
||||
replacing them with the macro Argument Clinic generated:
|
||||
|
||||
.. code-block:: none
|
||||
|
|
@ -1821,7 +1838,7 @@ This may mean that you get a complaint from Argument Clinic:
|
|||
|
||||
When this happens, just open your file, find the ``dump buffer`` block that
|
||||
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 :c:type:`PyMethodDef` structure where that macro is used.
|
||||
|
||||
|
||||
How to use Argument Clinic in Python files
|
||||
|
|
|
|||
Loading…
Reference in New Issue