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

---------

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Erlend E. Aasland <[email protected]>
Co-authored-by: Ezio Melotti <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>

Author: 5 people

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 <PyGetSetDef>` 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 <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;
+    }
+
+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: