Add "how to" for the setter Argument Clinic directive

python · corona10 · Dec 13, 2023 · Dec 10, 2023 · Dec 10, 2023 · Dec 10, 2023
commit 85a1ea8deaad869baca755dc386a34dae558fea9
diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst
@@ -2000,52 +2000,72 @@ The generated glue code looks like this:
 .. versionadded:: 3.13
 
 
-.. _clinic-howto-getter:
+.. _clinic-howto-getter-setter:
 
 How to generate a getter
 ------------------------
 
-"Getters" are C functions that facilitate property-like access for a class.
+"Getters" and "Setters" 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
+You can use the ``@getter`` and ``@setter`` 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
+This is example of ``@getter``-- taken from :cpy-file:`Modules/_io/textio.c` --
+shows the use of ``@getter`` and ``@setter`` 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
+    _io.TextIOWrapper._CHUNK_SIZE
+    [clinic start generated code]*/
+
+    /*[clinic input]
+    @critical_section
+    @setter
+    _io.TextIOWrapper._CHUNK_SIZE
     [clinic start generated code]*/
 
 The generated glue code looks like this:
 
 .. code-block:: c
 
     static PyObject *
-    _io__Buffered_closed_get(buffered *self, void *context)
+    _io_TextIOWrapper__CHUNK_SIZE_get(textio *self, void *Py_UNUSED(context))
     {
         PyObject *return_value = NULL;
 
         Py_BEGIN_CRITICAL_SECTION(self);
-        return_value = _io__Buffered_closed_get_impl(self);
+        return_value = _io_TextIOWrapper__CHUNK_SIZE_get_impl(self);
         Py_END_CRITICAL_SECTION();
 
         return return_value;
     }
 
+    static int
+    _io_TextIOWrapper__CHUNK_SIZE_set(textio *self, PyObject *value, void *Py_UNUSED(context))
+    {
+        int return_value;
+        Py_BEGIN_CRITICAL_SECTION(self);
+        return_value = _io_Te
8000
xtIOWrapper__CHUNK_SIZE_set_impl(self, value);
+        Py_END_CRITICAL_SECTION();
+        return return_value;
+    }
+
+Note that each of ``@getter`` and ``@setter`` should be declared at separated definitions.
 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
+   >>> import sys, _io
+   >>> a = _io.TextIOWrapper(sys.stdout)
+   >>> a._CHUNK_SIZE
+   8192
+   >>> a._CHUNK_SIZE = 30
+   >>> a._CHUNK_SIZE
+   30
 
 .. versionadded:: 3.13