[3.15] gh-87904: Document curses classes (GH-151643) (GH-152048)

Add docstrings for the curses.window, curses.error, curses.panel.panel
and curses.panel.error classes.  Document the panel class and its error
exception in curses.panel.rst, using the real lowercase panel name.
(cherry picked from commit 560ff8e2021d818555884622f6865f4a0d60756f)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

diff --git a/Doc/library/curses.panel.rst b/Doc/library/curses.panel.rst
index 2cfd522f34879a7668e7b25c89ed7d921142fc29..dd345bff428ad685a02ebcb2b37a363e31874a36 100644 (file)
--- a/Doc/library/curses.panel.rst
+++ b/Doc/library/curses.panel.rst
@@ -16,6 +16,14 @@ displayed.  Panels can be added, moved up or down in the stack, and removed.
 Functions
 ---------
 
+The module :mod:`!curses.panel` defines the following exception:
+
+
+.. exception:: error
+
+   Exception raised when a curses panel library function returns an error.
+
+
 The module :mod:`!curses.panel` defines the following functions:
 
 
@@ -48,73 +56,91 @@ The module :mod:`!curses.panel` defines the following functions:
 Panel objects
 -------------
 
-Panel objects, as returned by :func:`new_panel` above, are windows with a
-stacking order. There's always a window associated with a panel which determines
-the content, while the panel methods are responsible for the window's depth in
-the panel stack.
+.. raw:: html
+
+   <!-- Keep the old URL fragments working (see gh-89554) -->
+   <span id='curses.panel.Panel.above'></span>
+   <span id='curses.panel.Panel.below'></span>
+   <span id='curses.panel.Panel.bottom'></span>
+   <span id='curses.panel.Panel.hidden'></span>
+   <span id='curses.panel.Panel.hide'></span>
+   <span id='curses.panel.Panel.move'></span>
+   <span id='curses.panel.Panel.replace'></span>
+   <span id='curses.panel.Panel.set_userptr'></span>
+   <span id='curses.panel.Panel.show'></span>
+   <span id='curses.panel.Panel.top'></span>
+   <span id='curses.panel.Panel.userptr'></span>
+   <span id='curses.panel.Panel.window'></span>
+
+.. class:: panel
+
+   Panel objects, as returned by :func:`new_panel` above, are windows with a
+   stacking order.  There's always a window associated with a panel which
+   determines the content, while the panel methods are responsible for the
+   window's depth in the panel stack.
 
-Panel objects have the following methods:
+   Panel objects have the following methods:
 
 
-.. method:: Panel.above()
+.. method:: panel.above()
 
    Returns the panel above the current panel.
 
 
-.. method:: Panel.below()
+.. method:: panel.below()
 
    Returns the panel below the current panel.
 
 
-.. method:: Panel.bottom()
+.. method:: panel.bottom()
 
    Push the panel to the bottom of the stack.
 
 
-.. method:: Panel.hidden()
+.. method:: panel.hidden()
 
    Returns ``True`` if the panel is hidden (not visible), ``False`` otherwise.
 
 
-.. method:: Panel.hide()
+.. method:: panel.hide()
 
    Hide the panel. This does not delete the object, it just makes the window on
    screen invisible.
 
 
-.. method:: Panel.move(y, x)
+.. method:: panel.move(y, x)
 
    Move the panel to the screen coordinates ``(y, x)``.
 
 
-.. method:: Panel.replace(win)
+.. method:: panel.replace(win)
 
    Change the window associated with the panel to the window *win*.
 
 
-.. method:: Panel.set_userptr(obj)
+.. method:: panel.set_userptr(obj)
 
    Set the panel's user pointer to *obj*. This is used to associate an arbitrary
    piece of data with the panel, and can be any Python object.
 
 
-.. method:: Panel.show()
+.. method:: panel.show()
 
    Display the panel (which might have been hidden), placing it on top of
    the panel stack.
 
 
-.. method:: Panel.top()
+.. method:: panel.top()
 
    Push panel to the top of the stack.
 
 
-.. method:: Panel.userptr()
+.. method:: panel.userptr()
 
    Returns the user pointer for the panel.  This might be any Python object.
 
 
-.. method:: Panel.window()
+.. method:: panel.window()
 
    Returns the window object associated with the panel.
 

diff --git a/Modules/_curses_panel.c b/Modules/_curses_panel.c
index 411e8187e5b4470f8b6d446ec23791a0c54576eb..c192ce5f05452fed842ee8fa6fc4cf20792b4222 100644 (file)
--- a/Modules/_curses_panel.c
+++ b/Modules/_curses_panel.c
@@ -672,7 +672,13 @@ static PyMethodDef PyCursesPanel_Methods[] = {
 
 /* -------------------------------------------------------*/
 
+PyDoc_STRVAR(PyCursesPanel_Type_doc,
+"A curses panel.\n"
+"\n"
+"Panel objects are returned by new_panel().");
+
 static PyType_Slot PyCursesPanel_Type_slots[] = {
+    {Py_tp_doc, (void *)PyCursesPanel_Type_doc},
     {Py_tp_clear, PyCursesPanel_Clear},
     {Py_tp_dealloc, PyCursesPanel_Dealloc},
     {Py_tp_traverse, PyCursesPanel_Traverse},
@@ -821,8 +827,10 @@ _curses_panel_exec(PyObject *mod)
     }
 
     /* For exception _curses_panel.error */
-    state->error = PyErr_NewException(
-        "_curses_panel.error", NULL, NULL);
+    state->error = PyErr_NewExceptionWithDoc(
+        "_curses_panel.error",
+        "Exception raised when a curses panel library function returns an error.",
+        NULL, NULL);
 
     if (PyModule_AddObjectRef(mod, "error", state->error) < 0) {
         return -1;

diff --git a/Modules/_cursesmodule.c b/Modules/_cursesmodule.c
index 02a8e2c1b1bc1053d035bf79575bf2c1f510e4b1..b7195264c7f090b9b3861e7d9ef59481944e3220 100644 (file)
--- a/Modules/_cursesmodule.c
+++ b/Modules/_cursesmodule.c
@@ -3099,7 +3099,14 @@ static PyGetSetDef PyCursesWindow_getsets[] = {
     {NULL, NULL, NULL, NULL }  /* sentinel */
 };
 
+PyDoc_STRVAR(PyCursesWindow_Type_doc,
+"A curses window.\n"
+"\n"
+"Window objects are returned by initscr() and newwin(), and by the\n"
+"methods that create subwindows and pads.");
+
 static PyType_Slot PyCursesWindow_Type_slots[] = {
+    {Py_tp_doc, (void *)PyCursesWindow_Type_doc},
     {Py_tp_methods, PyCursesWindow_methods},
     {Py_tp_getset, PyCursesWindow_getsets},
     {Py_tp_dealloc, PyCursesWindow_dealloc},
@@ -5560,7 +5567,10 @@ cursesmodule_exec(PyObject *module)
     }
 
     /* For exception curses.error */
-    state->error = PyErr_NewException("_curses.error", NULL, NULL);
+    state->error = PyErr_NewExceptionWithDoc(
+        "_curses.error",
+        "Exception raised when a curses library function returns an error.",
+        NULL, NULL);
     if (state->error == NULL) {
         return -1;
     }