From 85a1ea8deaad869baca755dc386a34dae558fea9 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Sun, 10 Dec 2023 21:41:01 +0900 Subject: [PATCH 01/17] Add "how to" for the setter Argument Clinic directive --- development-tools/clinic.rst | 44 ++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index fe1361e88c..8466a76de2 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2000,25 +2000,31 @@ 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 ` 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 ` 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: @@ -2026,26 +2032,40 @@ 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_TextIOWrapper__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 From e2787571fe03581677c71e1b9fc8c5f65b7d7db4 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Sun, 10 Dec 2023 21:42:55 +0900 Subject: [PATCH 02/17] nit --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 8466a76de2..26e5ce4d5e 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2006,7 +2006,7 @@ How to generate a getter ------------------------ "Getters" and "Setters" are C functions that facilitate property-like access for a class. -See :c:type:`getter ` for details. +See :c:type:`getter ` and :c:type:`setter ` for details. You can use the ``@getter`` and ``@setter`` directive to generate an "impl" function for a getter using Argument Clinic. From 3a4661d24508958ec8e23596f2c4460341be2695 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Sun, 10 Dec 2023 21:44:16 +0900 Subject: [PATCH 03/17] nit --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 26e5ce4d5e..cb6aa552f4 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2010,7 +2010,7 @@ See :c:type:`getter ` and :c:type:`setter ` for detail You can use the ``@getter`` and ``@setter`` directive to generate an "impl" function for a getter using Argument Clinic. -This is example of ``@getter``-- taken from :cpy-file:`Modules/_io/textio.c` -- +This examples -- taken from :cpy-file:`Modules/_io/textio.c` -- shows the use of ``@getter`` and ``@setter`` in combination with the :ref:`@critical_section ` directive (which achieves thread safety without causing deadlocks between threads):: From 017fdc60bd46bd3d01bd13e1e60e81a266935ce5 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Sun, 10 Dec 2023 21:46:25 +0900 Subject: [PATCH 04/17] fix --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index cb6aa552f4..7e087b8c2d 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2010,7 +2010,7 @@ See :c:type:`getter ` and :c:type:`setter ` for detail You can use the ``@getter`` and ``@setter`` directive to generate an "impl" function for a getter using Argument Clinic. -This examples -- taken from :cpy-file:`Modules/_io/textio.c` -- +This example -- taken from :cpy-file:`Modules/_io/textio.c` -- shows the use of ``@getter`` and ``@setter`` in combination with the :ref:`@critical_section ` directive (which achieves thread safety without causing deadlocks between threads):: From 17d0f4dbcb807fd56f492e95ceb64a10329df2bc Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 11 Dec 2023 10:35:37 +0900 Subject: [PATCH 05/17] Apply suggestions from code review Co-authored-by: Hugo van Kemenade --- development-tools/clinic.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 7e087b8c2d..93ce27ba9b 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2000,12 +2000,13 @@ The generated glue code looks like this: .. versionadded:: 3.13 +.. _clinic-howto-getter: .. _clinic-howto-getter-setter: How to generate a getter ------------------------ -"Getters" and "Setters" 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 ` and :c:type:`setter ` for details. You can use the ``@getter`` and ``@setter`` directive to generate an "impl" function for a getter using Argument Clinic. @@ -2053,7 +2054,7 @@ The generated glue code looks like this: return return_value; } -Note that each of ``@getter`` and ``@setter`` should be declared at separated definitions. +Note that each of ``@getter`` and ``@setter`` should be declared in separated definitions. And then the implementation will work the same as a Python method which is decorated by :py:class:`property`. From f0195355af0415028481646908c52d0ec7c39127 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 11 Dec 2023 19:07:39 +0900 Subject: [PATCH 06/17] Apply suggestions from code review Co-authored-by: Ezio Melotti --- development-tools/clinic.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 93ce27ba9b..cd504013f3 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2011,7 +2011,7 @@ See :c:type:`getter ` and :c:type:`setter ` for detail 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/textio.c` -- +This example --- taken from :cpy-file:`Modules/_io/textio.c` --- shows the use of ``@getter`` and ``@setter`` in combination with the :ref:`@critical_section ` directive (which achieves thread safety without causing deadlocks between threads):: @@ -2054,9 +2054,9 @@ The generated glue code looks like this: return return_value; } -Note that each of ``@getter`` and ``@setter`` should be declared in separated definitions. -And then the implementation will work the same as a Python method which is +The implementation will then work the same as a Python method which is decorated by :py:class:`property`. +Note that each of ``@getter`` and ``@setter`` should be declared in separated definitions. .. code-block:: pycon From e53ba5d54d6c73337531172ee5ecb2cae098bab1 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 11 Dec 2023 22:56:06 +0900 Subject: [PATCH 07/17] Address code review --- development-tools/clinic.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index cd504013f3..5d7cbc9fba 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2000,11 +2000,10 @@ The generated glue code looks like this: .. versionadded:: 3.13 -.. _clinic-howto-getter: -.. _clinic-howto-getter-setter: +.. _clinic-howto-PyGetSetDef: -How to generate a getter ------------------------- +How to declare PyGetSetDef functions +------------------------------------ "Getters" and "setters" are C functions that facilitate property-like access for a class. See :c:type:`getter ` and :c:type:`setter ` for details. From a648144d2c3bbd59df57eadbef08837fb14bdf29 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 11 Dec 2023 23:10:44 +0900 Subject: [PATCH 08/17] nit --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 5d7cbc9fba..a04f47144c 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2000,7 +2000,7 @@ The generated glue code looks like this: .. versionadded:: 3.13 -.. _clinic-howto-PyGetSetDef: +.. _clinic-howto-pygetsetdef: How to declare PyGetSetDef functions ------------------------------------ From bc015ec0eae1241d3606021a043d185a0b6c91b8 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Tue, 12 Dec 2023 20:56:43 +0900 Subject: [PATCH 09/17] Apply suggestions from code review Co-authored-by: Erlend E. Aasland --- development-tools/clinic.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index a04f47144c..850919b09f 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2007,8 +2007,8 @@ How to declare PyGetSetDef functions "Getters" and "setters" are C functions that facilitate property-like access for a class. See :c:type:`getter ` and :c:type:`setter ` for details. -You can use the ``@getter`` and ``@setter`` directive to generate an "impl" function for a -getter using Argument Clinic. +You can use the ``@getter`` and ``@setter`` directives to generate +"impl" functions for a getters and setters in Argument Clinic. This example --- taken from :cpy-file:`Modules/_io/textio.c` --- shows the use of ``@getter`` and ``@setter`` in combination with @@ -2055,7 +2055,10 @@ The generated glue code looks like this: The implementation will then work the same as a Python method which is decorated by :py:class:`property`. -Note that each of ``@getter`` and ``@setter`` should be declared in separated definitions. +.. note:: + + Getters and setters must be declared as separate functions. + The "value" parameter for a "setter" is added implicitly by Argument Clinic. .. code-block:: pycon From 1ce8b1608e79ff50e5af0282791ebe50bc23fea5 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 12 Dec 2023 13:15:32 +0100 Subject: [PATCH 10/17] Update development-tools/clinic.rst --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 850919b09f..59b1954dcc 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2008,7 +2008,7 @@ How to declare PyGetSetDef functions "Getters" and "setters" are C functions that facilitate property-like access for a class. See :c:type:`getter ` and :c:type:`setter ` for details. You can use the ``@getter`` and ``@setter`` directives to generate -"impl" functions for a getters and setters in Argument Clinic. +"impl" functions for getters and setters in Argument Clinic. This example --- taken from :cpy-file:`Modules/_io/textio.c` --- shows the use of ``@getter`` and ``@setter`` in combination with From 031c5ebb3d4909e6463397be65c8f2d36a0c1348 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 13 Dec 2023 00:06:39 +0900 Subject: [PATCH 11/17] Apply suggestions from code review Co-authored-by: Erlend E. Aasland --- development-tools/clinic.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 59b1954dcc..de0200fe87 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2008,7 +2008,7 @@ How to declare PyGetSetDef functions "Getters" and "setters" are C functions that facilitate property-like access for a class. See :c:type:`getter ` and :c:type:`setter ` for details. You can use the ``@getter`` and ``@setter`` directives to generate -"impl" functions for getters and setters in Argument Clinic. +"impl" functions for these. This example --- taken from :cpy-file:`Modules/_io/textio.c` --- shows the use of ``@getter`` and ``@setter`` in combination with @@ -2053,8 +2053,6 @@ The generated glue code looks like this: return return_value; } -The implementation will then work the same as a Python method which is -decorated by :py:class:`property`. .. note:: Getters and setters must be declared as separate functions. From 85242c5cc284d4e01d255f2f779f0e24ffac8637 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 13 Dec 2023 10:18:43 +0900 Subject: [PATCH 12/17] Apply suggestions from code review Co-authored-by: Ezio Melotti --- development-tools/clinic.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index de0200fe87..0931dd3dfc 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2002,11 +2002,11 @@ The generated glue code looks like this: .. _clinic-howto-pygetsetdef: -How to declare PyGetSetDef functions ------------------------------------- +How to declare ``PyGetSetDef`` functions +---------------------------------------- -"Getters" and "setters" are C functions that facilitate property-like access for a class. -See :c:type:`getter ` and :c:type:`setter ` for details. +"Getters" and "setters" are C functions defined in a :c:type:`PyGetSetDef` struct + that facilitate property-like access for a class. You can use the ``@getter`` and ``@setter`` directives to generate "impl" functions for these. @@ -2056,7 +2056,7 @@ The generated glue code looks like this: .. note:: Getters and setters must be declared as separate functions. - The "value" parameter for a "setter" is added implicitly by Argument Clinic. + The *value* parameter for a "setter" is added implicitly by Argument Clinic. .. code-block:: pycon From 5f991964eb670d548fb6962f9fa659518f759261 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 13 Dec 2023 10:44:26 +0900 Subject: [PATCH 13/17] fix --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 0931dd3dfc..d29a4f4cd9 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2006,7 +2006,7 @@ How to declare ``PyGetSetDef`` functions ---------------------------------------- "Getters" and "setters" are C functions defined in a :c:type:`PyGetSetDef` struct - that facilitate property-like access for a class. +that facilitate property-like access for a class. You can use the ``@getter`` and ``@setter`` directives to generate "impl" functions for these. From 0eaa5d7c08ecf9125369e640c7b1111213194615 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 13 Dec 2023 22:41:36 +0900 Subject: [PATCH 14/17] Apply suggestions from code review Co-authored-by: Alex Waygood --- development-tools/clinic.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index d29a4f4cd9..527c42f149 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2002,11 +2002,11 @@ The generated glue code looks like this: .. _clinic-howto-pygetsetdef: -How to declare ``PyGetSetDef`` functions ----------------------------------------- +How to declare ``PyGetSetDef`` ("getter/setter") functions +---------------------------------------------------------- "Getters" and "setters" are C functions defined in a :c:type:`PyGetSetDef` struct -that facilitate property-like access for a class. +that facilitate :py:class:`property`-like access for a class. You can use the ``@getter`` and ``@setter`` directives to generate "impl" functions for these. From 6fce77ef5ba855854cc85fea75adad1674674134 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 13 Dec 2023 22:49:48 +0900 Subject: [PATCH 15/17] Address Alex's suggestion --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 527c42f149..7f01401c18 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2008,7 +2008,7 @@ How to declare ``PyGetSetDef`` ("getter/setter") functions "Getters" and "setters" are C functions defined in a :c:type:`PyGetSetDef` struct that facilitate :py:class:`property`-like access for a class. You can use the ``@getter`` and ``@setter`` directives to generate -"impl" functions for these. +"impl" functions for using Argument Clinic. This example --- taken from :cpy-file:`Modules/_io/textio.c` --- shows the use of ``@getter`` and ``@setter`` in combination with From c7c2f0b3e8d132aa1b7a3b726c8901d6c0a0d5fb Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 13 Dec 2023 22:50:55 +0900 Subject: [PATCH 16/17] Update development-tools/clinic.rst Co-authored-by: Alex Waygood --- development-tools/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 7f01401c18..eb1cc8a987 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2008,7 +2008,7 @@ How to declare ``PyGetSetDef`` ("getter/setter") functions "Getters" and "setters" are C functions defined in a :c:type:`PyGetSetDef` struct that facilitate :py:class:`property`-like access for a class. You can use the ``@getter`` and ``@setter`` directives to generate -"impl" functions for using Argument Clinic. +"impl" functions using Argument Clinic. This example --- taken from :cpy-file:`Modules/_io/textio.c` --- shows the use of ``@getter`` and ``@setter`` in combination with From ee3b3553d294c339f2a28d42d97a1dcdabb45f75 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 13 Dec 2023 23:00:03 +0900 Subject: [PATCH 17/17] Update development-tools/clinic.rst Co-authored-by: Alex Waygood --- development-tools/clinic.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index eb1cc8a987..bc1090ffea 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2058,6 +2058,9 @@ The generated glue code looks like this: Getters and setters must be declared as separate functions. The *value* parameter for a "setter" is added implicitly by Argument Clinic. +And then the implementation will work the same as a Python method which is +decorated by :py:class:`property`: + .. code-block:: pycon >>> import sys, _io