Visitar URL original
gh-64658: Expand Argument Clinic return converter docs by erlend-aasland 路 Pull Request #104175 路 python/cpython 路 GitHub
Skip to content

gh-64658: Expand Argument Clinic return converter docs #104175

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erlend-aasland merged 7 commits into from
May 5, 2023
Merged

gh-64658: Expand Argument Clinic return converter docs #104175

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3de3972
gh-64658: Amend Argument Clinic return converter docs
erlend-aasland May 4, 2023
e7233a4
Fix init return converter name
erlend-aasland May 4, 2023
28876a7
Sort the return converter table alphabetically
erlend-aasland May 4, 2023
c361abd
Further amendments
erlend-aasland May 4, 2023
fc83243
Add example
erlend-aasland May 4, 2023
88ed3c1
Update Doc/howto/clinic.rst
erlend-aasland May 5, 2023
7e24669
Update Doc/howto/clinic.rst
erlend-aasland May 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Add example
  • Loading branch information
@erlend-aasland
erlend-aasland committed May 4, 2023
commit fc832433d5b705183c2f60e4b799fd49fcce2b54
27 changes: 22 additions & 5 deletions Doc/howto/clinic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated
:c:type:`PyObject * <PyObject>`.
But your C function often computes some C type, then converts it into the
:c:type:`!PyObject *`
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated
at the last moment. Argument Clinic handles converting your inputs from Python types
into native C types鈥攚hy 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.

Expand Down Expand Up @@ -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),
Expand Down