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
37 changes: 37 additions & 0 deletions development-tools/clinic.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2001,6 +2001,43 @@ 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
to define a `getter <https://docs.python.org/3/c-api/structures.html#c.PyGetSetDef.get>`_.

Example from :cpy-file:`Modules/_io/bufferedio.c`::

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

The generated glue code looks like this.
Note that this example is a mixture using the ``@critical_section`` directive
to achieve thread safety without causing deadlocks between threads:

.. 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