From 4688572ecde9291f5a12014a309c7cdd9966a00f Mon Sep 17 00:00:00 2001 From: Lokesh Kumar Sahu Date: Thu, 5 Nov 2026 00:08:34 +0530 Subject: [PATCH] gh-1268: Document CReturnConverter --- development-tools/clinic/howto.rst | 11 +++++-- development-tools/clinic/index.rst | 53 ++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 3 deletions(-) diff --git a/development-tools/clinic/howto.rst b/development-tools/clinic/howto.rst index 1addc1a31..77d2354b3 100644 --- a/development-tools/clinic/howto.rst +++ b/development-tools/clinic/howto.rst @@ -784,6 +784,8 @@ You can see more examples of custom converters in the CPython source tree; grep the C files for the string ``CConverter``. +.. _clinic-howto-custom-return-converter: + How to write a custom return converter -------------------------------------- @@ -791,11 +793,14 @@ 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 :py:class:`!CReturnConverter`. +Return converters must subclass :py:class:`~clinic.CReturnConverter`. +See :py:class:`~clinic.CReturnConverter` for a list of members you may wish to specify +or implement in your subclass. 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 :cpy-file:`Tools/clinic/clinic.py`, -specifically the implementation of :py:class:`!CReturnConverter` and +write your own return converter, please read +:cpy-file:`Tools/clinic/libclinic/return_converters.py`, +specifically the implementation of :py:class:`~clinic.CReturnConverter` and all its subclasses. diff --git a/development-tools/clinic/index.rst b/development-tools/clinic/index.rst index b6d351983..0d060845a 100644 --- a/development-tools/clinic/index.rst +++ b/development-tools/clinic/index.rst @@ -264,3 +264,56 @@ Classes for extending Argument Clinic 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`. + +.. class:: CReturnConverter + + The base class for all return converters. + See :ref:`clinic-howto-custom-return-converter` for how to subclass this class. + + .. attribute:: type + + The C type to use for this variable. + :attr:`!type` should be a Python string specifying the type, + for example, ``'int'``. + If this is a pointer type, the type string should end with ``' *'``. + Defaults to ``'PyObject *'``. + + .. attribute:: default + + The Python default value, or ``None``. + This attribute is currently unused by Argument Clinic. + + .. attribute:: py_default + + The default value as it should appear in Python code, as a string, + or ``None`` if there is no default. + + .. method:: return_converter_init() + + Hook for initializing custom return converters. + The base implementation takes no arguments. + Subclasses can override this method to accept keyword-only arguments + passed to the return converter in Argument Clinic declarations. + + .. method:: declare(data) + + Declares the return variable in the generated C code with the type + specified by :attr:`!type`, appending the declaration to + ``data.declarations`` and setting ``data.return_value``. + + .. method:: render(function, data) + + Generates the C code for converting the return value of the + implementation function into a :c:type:`PyObject * `. + Subclasses must implement this method. + + .. method:: err_occurred_if(expr, data) + + Appends a conditional check to the return conversion code that + jumps to the error exit label if *expr* evaluates to true and + an error has occurred (:c:func:`PyErr_Occurred`). + + .. method:: err_occurred_if_null_pointer(variable, data) + + Appends a check to the return conversion code that jumps to the error + exit label if *variable* is ``NULL``.