https://github.com/python/cpython/commit/560ff8e2021d818555884622f6865f4a0d60756f commit: 560ff8e2021d818555884622f6865f4a0d60756f branch: main author: Serhiy Storchaka <[email protected]> committer: serhiy-storchaka <[email protected]> date: 2026-06-24T06:08:34Z summary:
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) <[email protected]> files: M Doc/library/curses.panel.rst M Modules/_curses_panel.c M Modules/_cursesmodule.c diff --git a/Doc/library/curses.panel.rst b/Doc/library/curses.panel.rst index 2cfd522f34879a..dd345bff428ad6 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 + + <!-- 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 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 f0541b82ae070d..cf42a96b5ca3ae 100644 --- 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; } _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
