Skip to content

Add "how to" for the getter Argument Clinic directive. #1232

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.

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

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Nov 30, 2023
Merged
38 changes: 38 additions & 0 deletions development-tools/clinic.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2001,6 +2001,44 @@ The generated glue code looks like this:
.. versionadded:: 3.13


.. _clinic-howto-getter:

How to generate a getter
------------------------

You can use the ``@getter`` directive to generate an "impl" function
that defines a `getter <https://docs.python.org/3/c-api/structures.html#c.PyGetSetDef>`_.

This example --- taken from :cpy-file:`Modules/_io/bufferedio.c` ---
shows the use of ``@getter`` in combination with
the :ref:`@critical_section <clinic-howto-critical-sections>` directive
(which achieves thread safety without causing deadlocks between threads)::

/*[clinic input]
@critical_section
@getter
_io._Buffered.closed
[clinic start generated code]*/

The generated glue code looks like this:

.. code-block:: c

static PyObject *
_io__Buffered_closed_get(buffered *self, void *context)
{
PyObject *return_value = NULL;

Py_BEGIN_CRITICAL_SECTION(self);
return_value = _io__Buffered_closed_get_impl(self);
Py_END_CRITICAL_SECTION();

return return_value;
}

.. versionadded:: 3.13


.. _clinic-howto-deprecate-positional:
.. _clinic-howto-deprecate-keyword:

Expand Down