From e9d9ed2428482d200a71fe68f688bde4f9a7d6ec Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 27 Nov 2023 20:45:49 +0900 Subject: [PATCH 01/16] Add "how to" for the getter Argument Clinic directive. --- development-tools/clinic.rst | 37 ++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index aa0efddd6..1f9159023 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2001,6 +2001,43 @@ The generated glue code looks like this: .. versionadded:: 3.13 +.. _clinic-howto-getter: + +How to generate getter with Argument Clinic +-------------------------------------------- + +You can use ``@getter`` directive to generate "impl" function +to defining getter. + +Example from :cpy-file:`Modules/_io/bufferedio.c`:: + + /*[clinic input] + @critical_section + @getter + _io._Buffered.closed + [clinic start generated code]*/ + +The generate glue code looks like this. +Note that this example is mixture usage with ``@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: From 97e644e19522b1f1e6051a2d2e4968e6aaad32d5 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 27 Nov 2023 23:17:53 +0900 Subject: [PATCH 02/16] Apply suggestions from code review Co-authored-by: Hugo van Kemenade --- development-tools/clinic.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 1f9159023..93625f666 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2003,11 +2003,11 @@ The generated glue code looks like this: .. _clinic-howto-getter: -How to generate getter with Argument Clinic --------------------------------------------- +How to generate a getter +------------------------ -You can use ``@getter`` directive to generate "impl" function -to defining getter. +You can use the ``@getter`` directive to generate an "impl" function +to define a getter. Example from :cpy-file:`Modules/_io/bufferedio.c`:: @@ -2017,8 +2017,8 @@ Example from :cpy-file:`Modules/_io/bufferedio.c`:: _io._Buffered.closed [clinic start generated code]*/ -The generate glue code looks like this. -Note that this example is mixture usage with ``@critical_section`` directive +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 From 4dc72e95bcac5932474df9dca8220dd2805a2f1b Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Tue, 28 Nov 2023 19:04:44 +0900 Subject: [PATCH 03/16] Address code review --- 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 93625f666..86cf3cf27 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2007,7 +2007,7 @@ How to generate a getter ------------------------ You can use the ``@getter`` directive to generate an "impl" function -to define a getter. +to define a `getter `_. Example from :cpy-file:`Modules/_io/bufferedio.c`:: From 8cb31a91c0fd09cb84393d1f8dd89d36a5e6b669 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 29 Nov 2023 06:47:59 +0900 Subject: [PATCH 04/16] Update development-tools/clinic.rst Co-authored-by: Erlend E. Aasland --- 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 86cf3cf27..3390edbc5 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2007,7 +2007,7 @@ How to generate a getter ------------------------ You can use the ``@getter`` directive to generate an "impl" function -to define a `getter `_. +to define a `getter `_. Example from :cpy-file:`Modules/_io/bufferedio.c`:: From 1af671f9e9660469b73da4e0db0aebe257bb0642 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 29 Nov 2023 07:14:29 +0900 Subject: [PATCH 05/16] Address code review --- development-tools/clinic.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 3390edbc5..fc784cfbc 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2011,15 +2011,16 @@ to define a `getter ` directive +to achieve 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. -Note that this example is a mixture using the ``@critical_section`` directive -to achieve thread safety without causing deadlocks between threads: +The generated glue code looks like this.: .. code-block:: c From d631e8e1039939e6f4161513717633b38a79855e Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 29 Nov 2023 07:22:05 +0900 Subject: [PATCH 06/16] fix --- development-tools/clinic.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index fc784cfbc..a266bba0a 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2010,7 +2010,6 @@ You can use the ``@getter`` directive to generate an "impl" function to define a `getter `_. Example from :cpy-file:`Modules/_io/bufferedio.c`:: - Note that this example is a mixture using the :ref:`@critical_section ` directive to achieve thread safety without causing deadlocks between threads From 7a8bfae9e585c6417b3fc0525ea45f70d3783b0b Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Wed, 29 Nov 2023 10:28:54 +0900 Subject: [PATCH 07/16] Apply suggestions from code review Co-authored-by: Ezio Melotti --- development-tools/clinic.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index a266bba0a..f44f3e254 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2007,11 +2007,12 @@ How to generate a getter ------------------------ You can use the ``@getter`` directive to generate an "impl" function -to define a `getter `_. +that defines a `getter `_. -Example from :cpy-file:`Modules/_io/bufferedio.c`:: -Note that this example is a mixture using the :ref:`@critical_section ` directive -to achieve thread safety without causing deadlocks between threads +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 @@ -2019,7 +2020,7 @@ to achieve thread safety without causing deadlocks between threads _io._Buffered.closed [clinic start generated code]*/ -The generated glue code looks like this.: +The generated glue code looks like this: .. code-block:: c From 7248868540c0ef3388aca3bb9cfaffef1d5c81e3 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 12:22:40 +0900 Subject: [PATCH 08/16] Address code review --- development-tools/clinic.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index f44f3e254..6d08cd96a 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2007,7 +2007,7 @@ How to generate a getter ------------------------ You can use the ``@getter`` directive to generate an "impl" function -that defines a `getter `_. +that defines a :c:func:`getter `. This example --- taken from :cpy-file:`Modules/_io/bufferedio.c` --- shows the use of ``@getter`` in combination with @@ -2036,6 +2036,15 @@ The generated glue code looks like this: return return_value; } +And then the implementation will work the same as the Python method which is +decorated by :py:meth:`property.getter`. + +.. code-block:: python + >>> import _io + >>> a = _io._BufferedIOBase() + >>> a.closed + False + .. versionadded:: 3.13 From 9761c60667a708c5eeb14644a1b8100d3f5aa540 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 12:27:35 +0900 Subject: [PATCH 09/16] Fix REPL --- development-tools/clinic.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 6d08cd96a..4a2d5185b 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2037,9 +2037,10 @@ The generated glue code looks like this: } And then the implementation will work the same as the Python method which is -decorated by :py:meth:`property.getter`. +decorated by :meth:`property.getter`. .. code-block:: python + >>> import _io >>> a = _io._BufferedIOBase() >>> a.closed From 45a72503314f35b5eb0689afe9f8eebfa79b25f3 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 12:31:08 +0900 Subject: [PATCH 10/16] Fix --- development-tools/clinic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 4a2d5185b..3ad6ed734 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2007,7 +2007,7 @@ How to generate a getter ------------------------ You can use the ``@getter`` directive to generate an "impl" function -that defines a :c:func:`getter `. +that defines a `getter `_. This example --- taken from :cpy-file:`Modules/_io/bufferedio.c` --- shows the use of ``@getter`` in combination with @@ -2037,7 +2037,7 @@ The generated glue code looks like this: } And then the implementation will work the same as the Python method which is -decorated by :meth:`property.getter`. +decorated by `property `_. .. code-block:: python From 65145a92eeb1db7bf9e2642ff7aa8d5757e897e7 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 12:33:24 +0900 Subject: [PATCH 11/16] Fix URL --- 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 3ad6ed734..deeac6fcd 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2037,7 +2037,7 @@ The generated glue code looks like this: } And then the implementation will work the same as the Python method which is -decorated by `property `_. +decorated by `property `_. .. code-block:: python From 7511cbf016aaa1c2935482b746d745b58aa78d70 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 19:57:50 +0900 Subject: [PATCH 12/16] Address code review --- 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 deeac6fcd..7e97f9b8e 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2007,7 +2007,7 @@ How to generate a getter ------------------------ You can use the ``@getter`` directive to generate an "impl" function -that defines a `getter `_. +that defines a :c:type:`getter `. This example --- taken from :cpy-file:`Modules/_io/bufferedio.c` --- shows the use of ``@getter`` in combination with From 5f48ac0a8c23bd75a02bd8e972d6166e28e1e210 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 20:48:05 +0900 Subject: [PATCH 13/16] Apply suggestions from code review Co-authored-by: Erlend E. Aasland Co-authored-by: Alex Waygood --- development-tools/clinic.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 7e97f9b8e..fc94264e7 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2006,8 +2006,9 @@ The generated glue code looks like this: How to generate a getter ------------------------ -You can use the ``@getter`` directive to generate an "impl" function -that defines a :c:type:`getter `. +"Getters" are C functions that facilitate property-like access for a type. +See :c:type:`getter ` for details. +You can use the ``@getter`` directive to generate an "impl" function for a getter. This example --- taken from :cpy-file:`Modules/_io/bufferedio.c` --- shows the use of ``@getter`` in combination with @@ -2037,9 +2038,9 @@ The generated glue code looks like this: } And then the implementation will work the same as the Python method which is -decorated by `property `_. +decorated by :py:func:`property`. -.. code-block:: python +.. code-block:: pycon >>> import _io >>> a = _io._BufferedIOBase() From 2b2d38b691eb43141be981da6c9470faf854bf49 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 20:49:46 +0900 Subject: [PATCH 14/16] 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 fc94264e7..75731ae29 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2038,7 +2038,7 @@ The generated glue code looks like this: } And then the implementation will work the same as the Python method which is -decorated by :py:func:`property`. +decorated by :py:class:`property`. .. code-block:: pycon From a630aecea631c250bceaa2e35ff7d10c86a41731 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 22:01:51 +0900 Subject: [PATCH 15/16] Apply suggestions from code review Co-authored-by: Alex Waygood --- development-tools/clinic.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 75731ae29..6cc2c62e4 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2006,11 +2006,12 @@ The generated glue code looks like this: How to generate a getter ------------------------ -"Getters" are C functions that facilitate property-like access for a type. +"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. +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` --- +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):: From 8d5ffd11db1ac9faf47364252d5d92d6ac03f392 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Thu, 30 Nov 2023 22:02:01 +0900 Subject: [PATCH 16/16] 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 6cc2c62e4..5bc4e03f1 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2038,7 +2038,7 @@ The generated glue code looks like this: return return_value; } -And then the implementation will work the same as the Python method which is +And then the implementation will work the same as a Python method which is decorated by :py:class:`property`. .. code-block:: pycon