gh-112205: Support docstring for `@getter` (#113160)

---------

Co-authored-by: Erlend E. Aasland <erlend@python.org>

diff --git a/Lib/test/clinic.test.c b/Lib/test/clinic.test.c
index a6a21664bb82a1a0a8a42010e8f96bb0f00efbe4..b15aeb898d35a1235973adad43a4221d4d7fa50b 100644 (file)
--- a/Lib/test/clinic.test.c
+++ b/Lib/test/clinic.test.c
@@ -4956,11 +4956,16 @@ Test_meth_coexist_impl(TestObj *self)
 Test.property
 [clinic start generated code]*/
 
+#if defined(Test_property_HAS_DOCSTR)
+#  define Test_property_DOCSTR Test_property__doc__
+#else
+#  define Test_property_DOCSTR NULL
+#endif
 #if defined(TEST_PROPERTY_GETSETDEF)
 #  undef TEST_PROPERTY_GETSETDEF
-#  define TEST_PROPERTY_GETSETDEF {"property", (getter)Test_property_get, (setter)Test_property_set, NULL},
+#  define TEST_PROPERTY_GETSETDEF {"property", (getter)Test_property_get, (setter)Test_property_set, Test_property_DOCSTR},
 #else
-#  define TEST_PROPERTY_GETSETDEF {"property", (getter)Test_property_get, NULL, NULL},
+#  define TEST_PROPERTY_GETSETDEF {"property", (getter)Test_property_get, NULL, Test_property_DOCSTR},
 #endif
 
 static PyObject *
@@ -4974,16 +4979,21 @@ Test_property_get(TestObj *self, void *Py_UNUSED(context))
 
 static PyObject *
 Test_property_get_impl(TestObj *self)
-/*[clinic end generated code: output=af8140b692e0e2f1 input=2d92b3449fbc7d2b]*/
+/*[clinic end generated code: output=27b519719d992e03 input=2d92b3449fbc7d2b]*/
 
 /*[clinic input]
 @setter
 Test.property
 [clinic start generated code]*/
 
+#if defined(TEST_PROPERTY_HAS_DOCSTR)
+#  define Test_property_DOCSTR Test_property__doc__
+#else
+#  define Test_property_DOCSTR NULL
+#endif
 #if defined(TEST_PROPERTY_GETSETDEF)
 #  undef TEST_PROPERTY_GETSETDEF
-#  define TEST_PROPERTY_GETSETDEF {"property", (getter)Test_property_get, (setter)Test_property_set, NULL},
+#  define TEST_PROPERTY_GETSETDEF {"property", (getter)Test_property_get, (setter)Test_property_set, Test_property_DOCSTR},
 #else
 #  define TEST_PROPERTY_GETSETDEF {"property", NULL, (setter)Test_property_set, NULL},
 #endif
@@ -4999,7 +5009,7 @@ Test_property_set(TestObj *self, PyObject *value, void *Py_UNUSED(context))
 
 static int
 Test_property_set_impl(TestObj *self, PyObject *value)
-/*[clinic end generated code: output=f3eba6487d7550e2 input=3bc3f46a23c83a88]*/
+/*[clinic end generated code: output=9797cd03c5204ddb input=3bc3f46a23c83a88]*/
 
 /*[clinic input]
 output push

diff --git a/Lib/test/test_clinic.py b/Lib/test/test_clinic.py
index 6c6bd4e75a0b0282916bdc96094d43f7c5080362..714fa6d7cb328f82a88bbcb619e34f818e6b6156 100644 (file)
--- a/Lib/test/test_clinic.py
+++ b/Lib/test/test_clinic.py
@@ -2221,6 +2221,21 @@ class ClinicParserTest(TestCase):
                 expected_error = f"{annotation} method cannot define parameters"
                 self.expect_failure(block, expected_error)
 
+    def test_setter_docstring(self):
+        block = """
+            module foo
+            class Foo "" ""
+            @setter
+            Foo.property
+
+            foo
+
+            bar
+            [clinic start generated code]*/
+        """
+        expected_error = "docstrings are only supported for @getter, not @setter"
+        self.expect_failure(block, expected_error)
+
     def test_duplicate_getset(self):
         annotations = ["@getter", "@setter"]
         for annotation in annotations:

diff --git a/Modules/_io/clinic/bufferedio.c.h b/Modules/_io/clinic/bufferedio.c.h
index ec46d5409a3d824157266efcd111956b869e59ca..d5bec5f71f5be88db69e11bb2bd7f92d24176a08 100644 (file)
--- a/Modules/_io/clinic/bufferedio.c.h
+++ b/Modules/_io/clinic/bufferedio.c.h
@@ -327,11 +327,16 @@ _io__Buffered_simple_flush(buffered *self, PyObject *Py_UNUSED(ignored))
     return return_value;
 }
 
+#if defined(_io__Buffered_closed_HAS_DOCSTR)
+#  define _io__Buffered_closed_DOCSTR _io__Buffered_closed__doc__
+#else
+#  define _io__Buffered_closed_DOCSTR NULL
+#endif
 #if defined(_IO__BUFFERED_CLOSED_GETSETDEF)
 #  undef _IO__BUFFERED_CLOSED_GETSETDEF
-#  define _IO__BUFFERED_CLOSED_GETSETDEF {"closed", (getter)_io__Buffered_closed_get, (setter)_io__Buffered_closed_set, NULL},
+#  define _IO__BUFFERED_CLOSED_GETSETDEF {"closed", (getter)_io__Buffered_closed_get, (setter)_io__Buffered_closed_set, _io__Buffered_closed_DOCSTR},
 #else
-#  define _IO__BUFFERED_CLOSED_GETSETDEF {"closed", (getter)_io__Buffered_closed_get, NULL, NULL},
+#  define _IO__BUFFERED_CLOSED_GETSETDEF {"closed", (getter)_io__Buffered_closed_get, NULL, _io__Buffered_closed_DOCSTR},
 #endif
 
 static PyObject *
@@ -464,11 +469,16 @@ _io__Buffered_writable(buffered *self, PyObject *Py_UNUSED(ignored))
     return return_value;
 }
 
+#if defined(_io__Buffered_name_HAS_DOCSTR)
+#  define _io__Buffered_name_DOCSTR _io__Buffered_name__doc__
+#else
+#  define _io__Buffered_name_DOCSTR NULL
+#endif
 #if defined(_IO__BUFFERED_NAME_GETSETDEF)
 #  undef _IO__BUFFERED_NAME_GETSETDEF
-#  define _IO__BUFFERED_NAME_GETSETDEF {"name", (getter)_io__Buffered_name_get, (setter)_io__Buffered_name_set, NULL},
+#  define _IO__BUFFERED_NAME_GETSETDEF {"name", (getter)_io__Buffered_name_get, (setter)_io__Buffered_name_set, _io__Buffered_name_DOCSTR},
 #else
-#  define _IO__BUFFERED_NAME_GETSETDEF {"name", (getter)_io__Buffered_name_get, NULL, NULL},
+#  define _IO__BUFFERED_NAME_GETSETDEF {"name", (getter)_io__Buffered_name_get, NULL, _io__Buffered_name_DOCSTR},
 #endif
 
 static PyObject *
@@ -486,11 +496,16 @@ _io__Buffered_name_get(buffered *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+#if defined(_io__Buffered_mode_HAS_DOCSTR)
+#  define _io__Buffered_mode_DOCSTR _io__Buffered_mode__doc__
+#else
+#  define _io__Buffered_mode_DOCSTR NULL
+#endif
 #if defined(_IO__BUFFERED_MODE_GETSETDEF)
 #  undef _IO__BUFFERED_MODE_GETSETDEF
-#  define _IO__BUFFERED_MODE_GETSETDEF {"mode", (getter)_io__Buffered_mode_get, (setter)_io__Buffered_mode_set, NULL},
+#  define _IO__BUFFERED_MODE_GETSETDEF {"mode", (getter)_io__Buffered_mode_get, (setter)_io__Buffered_mode_set, _io__Buffered_mode_DOCSTR},
 #else
-#  define _IO__BUFFERED_MODE_GETSETDEF {"mode", (getter)_io__Buffered_mode_get, NULL, NULL},
+#  define _IO__BUFFERED_MODE_GETSETDEF {"mode", (getter)_io__Buffered_mode_get, NULL, _io__Buffered_mode_DOCSTR},
 #endif
 
 static PyObject *
@@ -1230,4 +1245,4 @@ skip_optional_pos:
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=0999c33f666dc692 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=442b05b9a117df6c input=a9049054013a1b77]*/

diff --git a/Modules/_io/clinic/stringio.c.h b/Modules/_io/clinic/stringio.c.h
index fc2962d1c9c9a704706ae4eb9b32add3cfdf57f1..6bdb2181985f7d6fc474e766a287ec964feb278c 100644 (file)
--- a/Modules/_io/clinic/stringio.c.h
+++ b/Modules/_io/clinic/stringio.c.h
@@ -475,11 +475,16 @@ _io_StringIO___setstate__(stringio *self, PyObject *state)
     return return_value;
 }
 
+#if defined(_io_StringIO_closed_HAS_DOCSTR)
+#  define _io_StringIO_closed_DOCSTR _io_StringIO_closed__doc__
+#else
+#  define _io_StringIO_closed_DOCSTR NULL
+#endif
 #if defined(_IO_STRINGIO_CLOSED_GETSETDEF)
 #  undef _IO_STRINGIO_CLOSED_GETSETDEF
-#  define _IO_STRINGIO_CLOSED_GETSETDEF {"closed", (getter)_io_StringIO_closed_get, (setter)_io_StringIO_closed_set, NULL},
+#  define _IO_STRINGIO_CLOSED_GETSETDEF {"closed", (getter)_io_StringIO_closed_get, (setter)_io_StringIO_closed_set, _io_StringIO_closed_DOCSTR},
 #else
-#  define _IO_STRINGIO_CLOSED_GETSETDEF {"closed", (getter)_io_StringIO_closed_get, NULL, NULL},
+#  define _IO_STRINGIO_CLOSED_GETSETDEF {"closed", (getter)_io_StringIO_closed_get, NULL, _io_StringIO_closed_DOCSTR},
 #endif
 
 static PyObject *
@@ -497,11 +502,16 @@ _io_StringIO_closed_get(stringio *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+#if defined(_io_StringIO_line_buffering_HAS_DOCSTR)
+#  define _io_StringIO_line_buffering_DOCSTR _io_StringIO_line_buffering__doc__
+#else
+#  define _io_StringIO_line_buffering_DOCSTR NULL
+#endif
 #if defined(_IO_STRINGIO_LINE_BUFFERING_GETSETDEF)
 #  undef _IO_STRINGIO_LINE_BUFFERING_GETSETDEF
-#  define _IO_STRINGIO_LINE_BUFFERING_GETSETDEF {"line_buffering", (getter)_io_StringIO_line_buffering_get, (setter)_io_StringIO_line_buffering_set, NULL},
+#  define _IO_STRINGIO_LINE_BUFFERING_GETSETDEF {"line_buffering", (getter)_io_StringIO_line_buffering_get, (setter)_io_StringIO_line_buffering_set, _io_StringIO_line_buffering_DOCSTR},
 #else
-#  define _IO_STRINGIO_LINE_BUFFERING_GETSETDEF {"line_buffering", (getter)_io_StringIO_line_buffering_get, NULL, NULL},
+#  define _IO_STRINGIO_LINE_BUFFERING_GETSETDEF {"line_buffering", (getter)_io_StringIO_line_buffering_get, NULL, _io_StringIO_line_buffering_DOCSTR},
 #endif
 
 static PyObject *
@@ -519,11 +529,16 @@ _io_StringIO_line_buffering_get(stringio *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+#if defined(_io_StringIO_newlines_HAS_DOCSTR)
+#  define _io_StringIO_newlines_DOCSTR _io_StringIO_newlines__doc__
+#else
+#  define _io_StringIO_newlines_DOCSTR NULL
+#endif
 #if defined(_IO_STRINGIO_NEWLINES_GETSETDEF)
 #  undef _IO_STRINGIO_NEWLINES_GETSETDEF
-#  define _IO_STRINGIO_NEWLINES_GETSETDEF {"newlines", (getter)_io_StringIO_newlines_get, (setter)_io_StringIO_newlines_set, NULL},
+#  define _IO_STRINGIO_NEWLINES_GETSETDEF {"newlines", (getter)_io_StringIO_newlines_get, (setter)_io_StringIO_newlines_set, _io_StringIO_newlines_DOCSTR},
 #else
-#  define _IO_STRINGIO_NEWLINES_GETSETDEF {"newlines", (getter)_io_StringIO_newlines_get, NULL, NULL},
+#  define _IO_STRINGIO_NEWLINES_GETSETDEF {"newlines", (getter)_io_StringIO_newlines_get, NULL, _io_StringIO_newlines_DOCSTR},
 #endif
 
 static PyObject *
@@ -540,4 +555,4 @@ _io_StringIO_newlines_get(stringio *self, void *Py_UNUSED(context))
 
     return return_value;
 }
-/*[clinic end generated code: output=27726751d98ab617 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=9ffea20cd32d4cd8 input=a9049054013a1b77]*/

diff --git a/Modules/_io/clinic/textio.c.h b/Modules/_io/clinic/textio.c.h
index f24f65f0c1d4f9c6a561054d689c2e6a9fd390da..23b3cc8d71e098c1766ce4d70607135c5266b558 100644 (file)
--- a/Modules/_io/clinic/textio.c.h
+++ b/Modules/_io/clinic/textio.c.h
@@ -201,6 +201,89 @@ exit:
     return return_value;
 }
 
+PyDoc_STRVAR(_io__TextIOBase_encoding__doc__,
+"Encoding of the text stream.\n"
+"\n"
+"Subclasses should override.");
+#define _io__TextIOBase_encoding_HAS_DOCSTR
+
+#if defined(_io__TextIOBase_encoding_HAS_DOCSTR)
+#  define _io__TextIOBase_encoding_DOCSTR _io__TextIOBase_encoding__doc__
+#else
+#  define _io__TextIOBase_encoding_DOCSTR NULL
+#endif
+#if defined(_IO__TEXTIOBASE_ENCODING_GETSETDEF)
+#  undef _IO__TEXTIOBASE_ENCODING_GETSETDEF
+#  define _IO__TEXTIOBASE_ENCODING_GETSETDEF {"encoding", (getter)_io__TextIOBase_encoding_get, (setter)_io__TextIOBase_encoding_set, _io__TextIOBase_encoding_DOCSTR},
+#else
+#  define _IO__TEXTIOBASE_ENCODING_GETSETDEF {"encoding", (getter)_io__TextIOBase_encoding_get, NULL, _io__TextIOBase_encoding_DOCSTR},
+#endif
+
+static PyObject *
+_io__TextIOBase_encoding_get_impl(PyObject *self);
+
+static PyObject *
+_io__TextIOBase_encoding_get(PyObject *self, void *Py_UNUSED(context))
+{
+    return _io__TextIOBase_encoding_get_impl(self);
+}
+
+PyDoc_STRVAR(_io__TextIOBase_newlines__doc__,
+"Line endings translated so far.\n"
+"\n"
+"Only line endings translated during reading are considered.\n"
+"\n"
+"Subclasses should override.");
+#define _io__TextIOBase_newlines_HAS_DOCSTR
+
+#if defined(_io__TextIOBase_newlines_HAS_DOCSTR)
+#  define _io__TextIOBase_newlines_DOCSTR _io__TextIOBase_newlines__doc__
+#else
+#  define _io__TextIOBase_newlines_DOCSTR NULL
+#endif
+#if defined(_IO__TEXTIOBASE_NEWLINES_GETSETDEF)
+#  undef _IO__TEXTIOBASE_NEWLINES_GETSETDEF
+#  define _IO__TEXTIOBASE_NEWLINES_GETSETDEF {"newlines", (getter)_io__TextIOBase_newlines_get, (setter)_io__TextIOBase_newlines_set, _io__TextIOBase_newlines_DOCSTR},
+#else
+#  define _IO__TEXTIOBASE_NEWLINES_GETSETDEF {"newlines", (getter)_io__TextIOBase_newlines_get, NULL, _io__TextIOBase_newlines_DOCSTR},
+#endif
+
+static PyObject *
+_io__TextIOBase_newlines_get_impl(PyObject *self);
+
+static PyObject *
+_io__TextIOBase_newlines_get(PyObject *self, void *Py_UNUSED(context))
+{
+    return _io__TextIOBase_newlines_get_impl(self);
+}
+
+PyDoc_STRVAR(_io__TextIOBase_errors__doc__,
+"The error setting of the decoder or encoder.\n"
+"\n"
+"Subclasses should override.");
+#define _io__TextIOBase_errors_HAS_DOCSTR
+
+#if defined(_io__TextIOBase_errors_HAS_DOCSTR)
+#  define _io__TextIOBase_errors_DOCSTR _io__TextIOBase_errors__doc__
+#else
+#  define _io__TextIOBase_errors_DOCSTR NULL
+#endif
+#if defined(_IO__TEXTIOBASE_ERRORS_GETSETDEF)
+#  undef _IO__TEXTIOBASE_ERRORS_GETSETDEF
+#  define _IO__TEXTIOBASE_ERRORS_GETSETDEF {"errors", (getter)_io__TextIOBase_errors_get, (setter)_io__TextIOBase_errors_set, _io__TextIOBase_errors_DOCSTR},
+#else
+#  define _IO__TEXTIOBASE_ERRORS_GETSETDEF {"errors", (getter)_io__TextIOBase_errors_get, NULL, _io__TextIOBase_errors_DOCSTR},
+#endif
+
+static PyObject *
+_io__TextIOBase_errors_get_impl(PyObject *self);
+
+static PyObject *
+_io__TextIOBase_errors_get(PyObject *self, void *Py_UNUSED(context))
+{
+    return _io__TextIOBase_errors_get_impl(self);
+}
+
 PyDoc_STRVAR(_io_IncrementalNewlineDecoder___init____doc__,
 "IncrementalNewlineDecoder(decoder, translate, errors=\'strict\')\n"
 "--\n"
@@ -1048,11 +1131,16 @@ _io_TextIOWrapper_close(textio *self, PyObject *Py_UNUSED(ignored))
     return return_value;
 }
 
+#if defined(_io_TextIOWrapper_name_HAS_DOCSTR)
+#  define _io_TextIOWrapper_name_DOCSTR _io_TextIOWrapper_name__doc__
+#else
+#  define _io_TextIOWrapper_name_DOCSTR NULL
+#endif
 #if defined(_IO_TEXTIOWRAPPER_NAME_GETSETDEF)
 #  undef _IO_TEXTIOWRAPPER_NAME_GETSETDEF
-#  define _IO_TEXTIOWRAPPER_NAME_GETSETDEF {"name", (getter)_io_TextIOWrapper_name_get, (setter)_io_TextIOWrapper_name_set, NULL},
+#  define _IO_TEXTIOWRAPPER_NAME_GETSETDEF {"name", (getter)_io_TextIOWrapper_name_get, (setter)_io_TextIOWrapper_name_set, _io_TextIOWrapper_name_DOCSTR},
 #else
-#  define _IO_TEXTIOWRAPPER_NAME_GETSETDEF {"name", (getter)_io_TextIOWrapper_name_get, NULL, NULL},
+#  define _IO_TEXTIOWRAPPER_NAME_GETSETDEF {"name", (getter)_io_TextIOWrapper_name_get, NULL, _io_TextIOWrapper_name_DOCSTR},
 #endif
 
 static PyObject *
@@ -1070,11 +1158,16 @@ _io_TextIOWrapper_name_get(textio *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+#if defined(_io_TextIOWrapper_closed_HAS_DOCSTR)
+#  define _io_TextIOWrapper_closed_DOCSTR _io_TextIOWrapper_closed__doc__
+#else
+#  define _io_TextIOWrapper_closed_DOCSTR NULL
+#endif
 #if defined(_IO_TEXTIOWRAPPER_CLOSED_GETSETDEF)
 #  undef _IO_TEXTIOWRAPPER_CLOSED_GETSETDEF
-#  define _IO_TEXTIOWRAPPER_CLOSED_GETSETDEF {"closed", (getter)_io_TextIOWrapper_closed_get, (setter)_io_TextIOWrapper_closed_set, NULL},
+#  define _IO_TEXTIOWRAPPER_CLOSED_GETSETDEF {"closed", (getter)_io_TextIOWrapper_closed_get, (setter)_io_TextIOWrapper_closed_set, _io_TextIOWrapper_closed_DOCSTR},
 #else
-#  define _IO_TEXTIOWRAPPER_CLOSED_GETSETDEF {"closed", (getter)_io_TextIOWrapper_closed_get, NULL, NULL},
+#  define _IO_TEXTIOWRAPPER_CLOSED_GETSETDEF {"closed", (getter)_io_TextIOWrapper_closed_get, NULL, _io_TextIOWrapper_closed_DOCSTR},
 #endif
 
 static PyObject *
@@ -1092,11 +1185,16 @@ _io_TextIOWrapper_closed_get(textio *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+#if defined(_io_TextIOWrapper_newlines_HAS_DOCSTR)
+#  define _io_TextIOWrapper_newlines_DOCSTR _io_TextIOWrapper_newlines__doc__
+#else
+#  define _io_TextIOWrapper_newlines_DOCSTR NULL
+#endif
 #if defined(_IO_TEXTIOWRAPPER_NEWLINES_GETSETDEF)
 #  undef _IO_TEXTIOWRAPPER_NEWLINES_GETSETDEF
-#  define _IO_TEXTIOWRAPPER_NEWLINES_GETSETDEF {"newlines", (getter)_io_TextIOWrapper_newlines_get, (setter)_io_TextIOWrapper_newlines_set, NULL},
+#  define _IO_TEXTIOWRAPPER_NEWLINES_GETSETDEF {"newlines", (getter)_io_TextIOWrapper_newlines_get, (setter)_io_TextIOWrapper_newlines_set, _io_TextIOWrapper_newlines_DOCSTR},
 #else
-#  define _IO_TEXTIOWRAPPER_NEWLINES_GETSETDEF {"newlines", (getter)_io_TextIOWrapper_newlines_get, NULL, NULL},
+#  define _IO_TEXTIOWRAPPER_NEWLINES_GETSETDEF {"newlines", (getter)_io_TextIOWrapper_newlines_get, NULL, _io_TextIOWrapper_newlines_DOCSTR},
 #endif
 
 static PyObject *
@@ -1114,11 +1212,16 @@ _io_TextIOWrapper_newlines_get(textio *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+#if defined(_io_TextIOWrapper_errors_HAS_DOCSTR)
+#  define _io_TextIOWrapper_errors_DOCSTR _io_TextIOWrapper_errors__doc__
+#else
+#  define _io_TextIOWrapper_errors_DOCSTR NULL
+#endif
 #if defined(_IO_TEXTIOWRAPPER_ERRORS_GETSETDEF)
 #  undef _IO_TEXTIOWRAPPER_ERRORS_GETSETDEF
-#  define _IO_TEXTIOWRAPPER_ERRORS_GETSETDEF {"errors", (getter)_io_TextIOWrapper_errors_get, (setter)_io_TextIOWrapper_errors_set, NULL},
+#  define _IO_TEXTIOWRAPPER_ERRORS_GETSETDEF {"errors", (getter)_io_TextIOWrapper_errors_get, (setter)_io_TextIOWrapper_errors_set, _io_TextIOWrapper_errors_DOCSTR},
 #else
-#  define _IO_TEXTIOWRAPPER_ERRORS_GETSETDEF {"errors", (getter)_io_TextIOWrapper_errors_get, NULL, NULL},
+#  define _IO_TEXTIOWRAPPER_ERRORS_GETSETDEF {"errors", (getter)_io_TextIOWrapper_errors_get, NULL, _io_TextIOWrapper_errors_DOCSTR},
 #endif
 
 static PyObject *
@@ -1136,11 +1239,16 @@ _io_TextIOWrapper_errors_get(textio *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+#if defined(_io_TextIOWrapper__CHUNK_SIZE_HAS_DOCSTR)
+#  define _io_TextIOWrapper__CHUNK_SIZE_DOCSTR _io_TextIOWrapper__CHUNK_SIZE__doc__
+#else
+#  define _io_TextIOWrapper__CHUNK_SIZE_DOCSTR NULL
+#endif
 #if defined(_IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF)
 #  undef _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF
-#  define _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF {"_CHUNK_SIZE", (getter)_io_TextIOWrapper__CHUNK_SIZE_get, (setter)_io_TextIOWrapper__CHUNK_SIZE_set, NULL},
+#  define _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF {"_CHUNK_SIZE", (getter)_io_TextIOWrapper__CHUNK_SIZE_get, (setter)_io_TextIOWrapper__CHUNK_SIZE_set, _io_TextIOWrapper__CHUNK_SIZE_DOCSTR},
 #else
-#  define _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF {"_CHUNK_SIZE", (getter)_io_TextIOWrapper__CHUNK_SIZE_get, NULL, NULL},
+#  define _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF {"_CHUNK_SIZE", (getter)_io_TextIOWrapper__CHUNK_SIZE_get, NULL, _io_TextIOWrapper__CHUNK_SIZE_DOCSTR},
 #endif
 
 static PyObject *
@@ -1158,9 +1266,14 @@ _io_TextIOWrapper__CHUNK_SIZE_get(textio *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+#if defined(_IO_TEXTIOWRAPPER__CHUNK_SIZE_HAS_DOCSTR)
+#  define _io_TextIOWrapper__CHUNK_SIZE_DOCSTR _io_TextIOWrapper__CHUNK_SIZE__doc__
+#else
+#  define _io_TextIOWrapper__CHUNK_SIZE_DOCSTR NULL
+#endif
 #if defined(_IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF)
 #  undef _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF
-#  define _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF {"_CHUNK_SIZE", (getter)_io_TextIOWrapper__CHUNK_SIZE_get, (setter)_io_TextIOWrapper__CHUNK_SIZE_set, NULL},
+#  define _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF {"_CHUNK_SIZE", (getter)_io_TextIOWrapper__CHUNK_SIZE_get, (setter)_io_TextIOWrapper__CHUNK_SIZE_set, _io_TextIOWrapper__CHUNK_SIZE_DOCSTR},
 #else
 #  define _IO_TEXTIOWRAPPER__CHUNK_SIZE_GETSETDEF {"_CHUNK_SIZE", NULL, (setter)_io_TextIOWrapper__CHUNK_SIZE_set, NULL},
 #endif
@@ -1179,4 +1292,4 @@ _io_TextIOWrapper__CHUNK_SIZE_set(textio *self, PyObject *value, void *Py_UNUSED
 
     return return_value;
 }
-/*[clinic end generated code: output=7af87bf848a5d3f3 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=d01aa598647c1385 input=a9049054013a1b77]*/

diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c
index 702336ca2aeb06852e76d9d20b43fa5557a92088..4507930c14bb50d9d83e42c52c57141daeabf8a4 100644 (file)
--- a/Modules/_io/textio.c
+++ b/Modules/_io/textio.c
@@ -131,40 +131,52 @@ _io__TextIOBase_write_impl(PyObject *self, PyTypeObject *cls,
     return _unsupported(state, "write");
 }
 
-PyDoc_STRVAR(textiobase_encoding_doc,
-    "Encoding of the text stream.\n"
-    "\n"
-    "Subclasses should override.\n"
-    );
+/*[clinic input]
+@getter
+_io._TextIOBase.encoding
+
+Encoding of the text stream.
+
+Subclasses should override.
+[clinic start generated code]*/
 
 static PyObject *
-textiobase_encoding_get(PyObject *self, void *context)
+_io__TextIOBase_encoding_get_impl(PyObject *self)
+/*[clinic end generated code: output=e0f5d8f548b92432 input=4736d7621dd38f43]*/
 {
     Py_RETURN_NONE;
 }
 
-PyDoc_STRVAR(textiobase_newlines_doc,
-    "Line endings translated so far.\n"
-    "\n"
-    "Only line endings translated during reading are considered.\n"
-    "\n"
-    "Subclasses should override.\n"
-    );
+/*[clinic input]
+@getter
+_io._TextIOBase.newlines
+
+Line endings translated so far.
+
+Only line endings translated during reading are considered.
+
+Subclasses should override.
+[clinic start generated code]*/
 
 static PyObject *
-textiobase_newlines_get(PyObject *self, void *context)
+_io__TextIOBase_newlines_get_impl(PyObject *self)
+/*[clinic end generated code: output=46ec147fb9f00c2a input=a5b196d076af1164]*/
 {
     Py_RETURN_NONE;
 }
 
-PyDoc_STRVAR(textiobase_errors_doc,
-    "The error setting of the decoder or encoder.\n"
-    "\n"
-    "Subclasses should override.\n"
-    );
+/*[clinic input]
+@getter
+_io._TextIOBase.errors
+
+The error setting of the decoder or encoder.
+
+Subclasses should override.
+[clinic start generated code]*/
 
 static PyObject *
-textiobase_errors_get(PyObject *self, void *context)
+_io__TextIOBase_errors_get_impl(PyObject *self)
+/*[clinic end generated code: output=c6623d6addcd087d input=974aa52d1db93a82]*/
 {
     Py_RETURN_NONE;
 }
@@ -179,9 +191,9 @@ static PyMethodDef textiobase_methods[] = {
 };
 
 static PyGetSetDef textiobase_getset[] = {
-    {"encoding", (getter)textiobase_encoding_get, NULL, textiobase_encoding_doc},
-    {"newlines", (getter)textiobase_newlines_get, NULL, textiobase_newlines_doc},
-    {"errors", (getter)textiobase_errors_get, NULL, textiobase_errors_doc},
+    _IO__TEXTIOBASE_ENCODING_GETSETDEF
+    _IO__TEXTIOBASE_NEWLINES_GETSETDEF
+    _IO__TEXTIOBASE_ERRORS_GETSETDEF
     {NULL}
 };
 

diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py
index 87feef1b82ca39a28dc56a3bc9c410d59af512fa..345459cf2fd623dcdb1043e169500ac11daa5751 100755 (executable)
--- a/Tools/clinic/clinic.py
+++ b/Tools/clinic/clinic.py
@@ -865,6 +865,11 @@ class CLanguage(Language):
         PyDoc_STRVAR({c_basename}__doc__,
         {docstring});
     """)
+    GETSET_DOCSTRING_PROTOTYPE_STRVAR: Final[str] = normalize_snippet("""
+        PyDoc_STRVAR({getset_basename}__doc__,
+        {docstring});
+        #define {getset_basename}_HAS_DOCSTR
+    """)
     IMPL_DEFINITION_PROTOTYPE: Final[str] = normalize_snippet("""
         static {impl_return_type}
         {c_basename}_impl({impl_parameters})
@@ -874,17 +879,27 @@ class CLanguage(Language):
             {{"{name}", {methoddef_cast}{c_basename}{methoddef_cast_end}, {methoddef_flags}, {c_basename}__doc__}},
     """)
     GETTERDEF_PROTOTYPE_DEFINE: Final[str] = normalize_snippet(r"""
+        #if defined({getset_basename}_HAS_DOCSTR)
+        #  define {getset_basename}_DOCSTR {getset_basename}__doc__
+        #else
+        #  define {getset_basename}_DOCSTR NULL
+        #endif
         #if defined({getset_name}_GETSETDEF)
         #  undef {getset_name}_GETSETDEF
-        #  define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, (setter){getset_basename}_set, NULL}},
+        #  define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, (setter){getset_basename}_set, {getset_basename}_DOCSTR}},
         #else
-        #  define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, NULL, NULL}},
+        #  define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, NULL, {getset_basename}_DOCSTR}},
         #endif
     """)
     SETTERDEF_PROTOTYPE_DEFINE: Final[str] = normalize_snippet(r"""
+        #if defined({getset_name}_HAS_DOCSTR)
+        #  define {getset_basename}_DOCSTR {getset_basename}__doc__
+        #else
+        #  define {getset_basename}_DOCSTR NULL
+        #endif
         #if defined({getset_name}_GETSETDEF)
         #  undef {getset_name}_GETSETDEF
-        #  define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, (setter){getset_basename}_set, NULL}},
+        #  define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, (setter){getset_basename}_set, {getset_basename}_DOCSTR}},
         #else
         #  define {getset_name}_GETSETDEF {{"{name}", NULL, (setter){getset_basename}_set, NULL}},
         #endif
@@ -1187,11 +1202,17 @@ class CLanguage(Language):
             docstring_prototype = docstring_definition = ''
         elif f.kind is GETTER:
             methoddef_define = self.GETTERDEF_PROTOTYPE_DEFINE
-            docstring_prototype = docstring_definition = ''
+            if f.docstring:
+                docstring_prototype = ''
+                docstring_definition = self.GETSET_DOCSTRING_PROTOTYPE_STRVAR
+            else:
+                docstring_prototype = docstring_definition = ''
         elif f.kind is SETTER:
+            if f.docstring:
+                fail("docstrings are only supported for @getter, not @setter")
             return_value_declaration = "int {return_value};"
             methoddef_define = self.SETTERDEF_PROTOTYPE_DEFINE
-            docstring_prototype = docstring_prototype = docstring_definition = ''
+            docstring_prototype = docstring_definition = ''
         else:
             docstring_prototype = self.DOCSTRING_PROTOTYPE_VAR
             docstring_definition = self.DOCSTRING_PROTOTYPE_STRVAR
@@ -6255,6 +6276,9 @@ class DSLParser:
         add(f.displayname)
         if self.forced_text_signature:
             add(self.forced_text_signature)
+        elif f.kind in {GETTER, SETTER}:
+            # @getter and @setter do not need signatures like a method or a function.
+            return ''
         else:
             add('(')
 
@@ -6427,8 +6451,8 @@ class DSLParser:
     def format_docstring(self) -> str:
         assert self.function is not None
         f = self.function
-        if f.kind.new_or_init and not f.docstring:
-            # don't render a docstring at all, no signature, nothing.
+        # For the following special cases, it does not make sense to render a docstring.
+        if f.kind in {METHOD_INIT, METHOD_NEW, GETTER, SETTER} and not f.docstring:
             return f.docstring
 
         # Enforce the summary line!