From 3de39728e603518c70f20742b57bea030ff9a14b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 May 2023 17:44:21 +0200 Subject: [PATCH 1/7] gh-64658: Amend Argument Clinic return converter docs --- Doc/howto/clinic.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 8a10fe327358c0..d878414406dccf 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1069,16 +1069,17 @@ Currently Argument Clinic supports only a few return converters: int unsigned int long - unsigned int + unsigned long size_t Py_ssize_t float double - DecodeFSDefault + __init__ None of these take parameters. For the first three, return -1 to indicate -error. For ``DecodeFSDefault``, the return type is ``const char *``; return a ``NULL`` -pointer to indicate an error. +error. +The ``__init__`` converter is a special return converter for ``__init__`` +functions. To see all the return converters Argument Clinic supports, along with their parameters (if any), From e7233a451e673d13f528dd373620b85efc688b96 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 May 2023 21:12:15 +0200 Subject: [PATCH 2/7] Fix init return converter name --- Doc/howto/clinic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index d878414406dccf..94c441b52f6766 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1074,11 +1074,11 @@ Currently Argument Clinic supports only a few return converters: Py_ssize_t float double - __init__ + init None of these take parameters. For the first three, return -1 to indicate error. -The ``__init__`` converter is a special return converter for ``__init__`` +The ``init`` converter is a special return converter for ``__init__`` functions. To see all the return converters Argument Clinic supports, along with From 28876a710c0f9bda9985955d8d21129ffcc2be58 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 May 2023 21:13:42 +0200 Subject: [PATCH 3/7] Sort the return converter table alphabetically --- Doc/howto/clinic.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 94c441b52f6766..7442de04fc3b93 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1066,15 +1066,15 @@ Currently Argument Clinic supports only a few return converters: .. code-block:: none bool + double + float + init int - unsigned int long - unsigned long - size_t Py_ssize_t - float - double - init + size_t + unsigned int + unsigned long None of these take parameters. For the first three, return -1 to indicate error. From c361abd2e4357e450af79b2fbf63e72b6315d26c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 May 2023 21:21:19 +0200 Subject: [PATCH 4/7] Further amendments --- Doc/howto/clinic.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 7442de04fc3b93..a0a1c8c789a6ad 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1068,7 +1068,6 @@ Currently Argument Clinic supports only a few return converters: bool double float - init int long Py_ssize_t @@ -1076,10 +1075,8 @@ Currently Argument Clinic supports only a few return converters: unsigned int unsigned long -None of these take parameters. For the first three, return -1 to indicate -error. -The ``init`` converter is a special return converter for ``__init__`` -functions. +None of these take parameters. +Return ``-1`` to indicate error. To see all the return converters Argument Clinic supports, along with their parameters (if any), From fc832433d5b705183c2f60e4b799fd49fcce2b54 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 4 May 2023 21:31:19 +0200 Subject: [PATCH 5/7] Add example --- Doc/howto/clinic.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index a0a1c8c789a6ad..d083aca8a5ec28 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1033,19 +1033,36 @@ you're not permitted to use: Using a return converter ------------------------ -By default the impl function Argument Clinic generates for you returns ``PyObject *``. -But your C function often computes some C type, then converts it into the ``PyObject *`` +By default the impl function Argument Clinic generates for you returns +:c:type:`PyObject * `. +But your C function often computes some C type, then converts it into the +:c:type:`!PyObject *` at the last moment. Argument Clinic handles converting your inputs from Python types into native C types—why not have it convert your return value from a native C type into a Python type too? That's what a "return converter" does. It changes your impl function to return some C type, then adds code to the generated (non-impl) function to handle converting -that value into the appropriate ``PyObject *``. +that value into the appropriate :c:type:`!PyObject *`. The syntax for return converters is similar to that of parameter converters. You specify the return converter like it was a return annotation on the -function itself. Return converters behave much the same as parameter converters; +function itself, using ``->`` notation. + +For example: + +.. code-block:: c + + /*[clinic input] + add -> int + + a: int + b: int + / + + [clinic start generated code]*/ + +Return converters behave much the same as parameter converters; they take arguments, the arguments are all keyword-only, and if you're not changing any of the default arguments you can omit the parentheses. @@ -1076,7 +1093,7 @@ Currently Argument Clinic supports only a few return converters: unsigned long None of these take parameters. -Return ``-1`` to indicate error. +For all of these, return ``-1`` to indicate error. To see all the return converters Argument Clinic supports, along with their parameters (if any), From 88ed3c1256ea216bdb8348f1f553cbe9a0556770 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 5 May 2023 13:07:35 +0200 Subject: [PATCH 6/7] Update Doc/howto/clinic.rst Co-authored-by: Alex Waygood --- Doc/howto/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index d083aca8a5ec28..45bed68c2484d5 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1033,7 +1033,7 @@ you're not permitted to use: Using a return converter ------------------------ -By default the impl function Argument Clinic generates for you returns +By default, the impl function Argument Clinic generates for you returns :c:type:`PyObject * `. But your C function often computes some C type, then converts it into the :c:type:`!PyObject *` From 7e2466941a5ceec3e7ca13f5addb46137cfe6695 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 5 May 2023 13:09:08 +0200 Subject: [PATCH 7/7] Update Doc/howto/clinic.rst --- Doc/howto/clinic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 45bed68c2484d5..6ebc2d9b0a71a9 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1035,8 +1035,8 @@ Using a return converter By default, the impl function Argument Clinic generates for you returns :c:type:`PyObject * `. -But your C function often computes some C type, then converts it into the -:c:type:`!PyObject *` +But your C function often computes some C type, +then converts it into the :c:type:`!PyObject *` at the last moment. Argument Clinic handles converting your inputs from Python types into native C types—why not have it convert your return value from a native C type into a Python type too?