From aedc050b4056fee8513c6557009dc948a308ec74 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 24 Jun 2026 09:08:34 +0300 Subject: [PATCH] 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. (cherry picked from commit 560ff8e2021d818555884622f6865f4a0d60756f) Co-authored-by: Serhiy Storchaka Co-authored-by: Claude Opus 4.8 (1M context) --- Doc/library/curses.panel.rst | 60 ++++++++++++++++++++++++++---------- Modules/_curses_panel.c | 12 ++++++-- Modules/_cursesmodule.c | 12 +++++++- 3 files changed, 64 insertions(+), 20 deletions(-) diff --git a/Doc/library/curses.panel.rst b/Doc/library/curses.panel.rst index 2cfd522f34879a7..dd345bff428ad68 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,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 + + + + + + + + + + + + + + + +.. 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 411e8187e5b4470..c192ce5f05452fe 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 02a8e2c1b1bc105..b7195264c7f090b 100644 --- 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; }