From 17262e14f23dd6366018ef7e0ae641f02dce5ab6 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 18 Jun 2026 13:56:43 +0300 Subject: [PATCH 1/2] gh-87904: Document curses classes 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. --- Doc/library/curses.panel.rst | 44 ++++++++++++++++++++++-------------- Modules/_curses_panel.c | 12 ++++++++-- Modules/_cursesmodule.c | 12 +++++++++- 3 files changed, 48 insertions(+), 20 deletions(-) diff --git a/Doc/library/curses.panel.rst b/Doc/library/curses.panel.rst index 2cfd522f34879a..0b0f65bfe19614 100644 --- 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,75 @@ 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. +.. 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 411e8187e5b447..c192ce5f05452f 100644 --- 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 01cb6786e88aec..ed32054926b383 100644 --- a/Modules/_cursesmodule.c +++ b/Modules/_cursesmodule.c @@ -3095,7 +3095,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}, @@ -5528,7 +5535,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; } From 5fa203bfbc12d43e4e1cce36106635de6a9519ee Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 18 Jun 2026 15:22:51 +0300 Subject: [PATCH 2/2] Add items to Doc/tools/removed-ids.txt. --- Doc/tools/removed-ids.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt index 81c0f098e4c8a8..c0c5f70fb5e9ba 100644 --- a/Doc/tools/removed-ids.txt +++ b/Doc/tools/removed-ids.txt @@ -33,3 +33,17 @@ reference/expressions.html: grammar-token-python-grammar-set_display # Moved to a different page c-api/typeobj.html: c.Py_tp_base c-api/typeobj.html: c.Py_tp_bases + +# curses.panel.panel is the correct class name. +library/curses.panel.html: curses.panel.Panel.above +library/curses.panel.html: curses.panel.Panel.below +library/curses.panel.html: curses.panel.Panel.bottom +library/curses.panel.html: curses.panel.Panel.hidden +library/curses.panel.html: curses.panel.Panel.hide +library/curses.panel.html: curses.panel.Panel.move +library/curses.panel.html: curses.panel.Panel.replace +library/curses.panel.html: curses.panel.Panel.set_userptr +library/curses.panel.html: curses.panel.Panel.show +library/curses.panel.html: curses.panel.Panel.top +library/curses.panel.html: curses.panel.Panel.userptr +library/curses.panel.html: curses.panel.Panel.window