diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index aa0efddd6..5bc4e03f1 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2001,6 +2001,56 @@ The generated glue code looks like this: .. versionadded:: 3.13 +.. _clinic-howto-getter: + +How to generate a getter +------------------------ + +"Getters" are C functions that facilitate property-like access for a class. +See :c:type:`getter ` for details. +You can use the ``@getter`` directive to generate an "impl" function for a +getter using Argument Clinic. + +This example -- taken from :cpy-file:`Modules/_io/bufferedio.c` -- +shows the use of ``@getter`` in combination with +the :ref:`@critical_section ` 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; + } + +And then the implementation will work the same as a Python method which is +decorated by :py:class:`property`. + +.. code-block:: pycon + + >>> import _io + >>> a = _io._BufferedIOBase() + >>> a.closed + False + +.. versionadded:: 3.13 + + .. _clinic-howto-deprecate-positional: .. _clinic-howto-deprecate-keyword: