gh-87904: Document curses classes (GH-151643)

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.

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 f0541b82ae070d7b6d5fedc4896e3accd6a8f053..cf42a96b5ca3ae7370e39850877eb5a7edb3aada 100644 (file)
--- a/Modules/_cursesmodule.c
+++ b/Modules/_cursesmodule.c
@@ -3426,7 +3426,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},
@@ -6003,7 +6010,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;
     }