@@ -2359,6 +2359,17 @@ def test_testcapi_no_segfault(self):
             class X(object):
                 p = property(_testcapi.test_with_docstring)
 
+    def test_subclass_with_nonwritable_doc(self):
+        # gh-98963: subclasses must have writable __doc__. A note is added to
+        # the exception in this surprising edge case.
+        class BadProperty(property):
+            __doc__ = property(lambda: None)
+        with self.assertRaises(AttributeError) as cm:
+            p = BadProperty(lambda: 123)
+        notes = cm.exception.__notes__
+        wanted = "subclasses of 'property' need to provide a writable __doc__"
+        self.assertTrue(any(note.startswith(wanted) for note in notes), notes)
+
     def test_properties_plus(self):
         class C(object):
             foo = property(doc="hello")
 
@@ -0,0 +1,3 @@
+Add a note to the ``AttributeError`` raised when instantiating a subclass of
+:py:type:`property` that does not have a writable ``__doc__`` attribute.
+(Creating such a subclass is possible via the C API.)
@@ -1826,8 +1826,28 @@ property_init_impl(propertyobject *self, PyObject *fget, PyObject *fset,
         int err = PyObject_SetAttr(
                     (PyObject *)self, &_Py_ID(__doc__), prop_doc);
         Py_XDECREF(prop_doc);
-        if (err < 0)
+        if (err < 0) {
+            if (PyErr_ExceptionMatches(PyExc_AttributeError)) {
+                // gh-98963: the subclass doesn't have a __dict__
+                // (probably it was subclassed using C API).
+                // Add a note to prevent surprises.
+                PyObject *type, *value, *traceback;
+                PyErr_Fetch(&type, &value, &traceback);
+                PyErr_NormalizeException(&type, &value, &traceback);
+                if (value) {
+                    PyObject_CallMethod(
+                        value, "add_note", "s",
+                        "subclasses of 'property' need to provide a writable "
+                        "__doc__ attribute (e.g. a __doc__ member or a "
+                        "__dict__) to avoid per-property docstrings being "
+                        "shadowed by the subclass docstring");
+                    // ignore errors while setting the note
+                    PyErr_Clear();
+                }
+                PyErr_Restore(type, value, traceback);
+            }
             return -1;
+        }
     }
 
     return 0;
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+Add a note to the ``AttributeError`` raised when instantiating a subclass of
	`2`	+:py:type:`property` that does not have a writable ``__doc__`` attribute.
	`3`	`+(Creating such a subclass is possible via the C API.)`