From: Serhiy Storchaka Date: Thu, 18 Jun 2026 10:52:26 +0000 (+0300) Subject: gh-151623: Add missing curses docstrings and document intrflush() (#151632) X-Git-Url: http://git.ipfire.org/index.cgi?a=commitdiff_plain;h=12add3822f458a3e107dff4176b4c4b991764ea7;p=thirdparty%2FPython%2Fcpython.git gh-151623: Add missing curses docstrings and document intrflush() (#151632) --- diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 085500860d12..5726aee5af89 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -330,6 +330,13 @@ The module :mod:`!curses` defines the following functions: cause the interpreter to exit. +.. function:: intrflush(flag) + + If *flag* is ``True``, pressing an interrupt key (interrupt, break, or quit) + will flush all output in the terminal driver queue. If *flag* is ``False``, + no flushing is done. + + .. function:: is_term_resized(nlines, ncols) Return ``True`` if :func:`resize_term` would modify the window structure, diff --git a/Modules/_cursesmodule.c b/Modules/_cursesmodule.c index cce93bea5751..01cb6786e88a 100644 --- a/Modules/_cursesmodule.c +++ b/Modules/_cursesmodule.c @@ -2937,39 +2937,71 @@ static PyMethodDef PyCursesWindow_methods[] = { _CURSES_WINDOW_BKGDSET_METHODDEF _CURSES_WINDOW_BORDER_METHODDEF _CURSES_WINDOW_BOX_METHODDEF - {"clear", PyCursesWindow_wclear, METH_NOARGS}, - {"clearok", PyCursesWindow_clearok, METH_VARARGS}, - {"clrtobot", PyCursesWindow_wclrtobot, METH_NOARGS}, - {"clrtoeol", PyCursesWindow_wclrtoeol, METH_NOARGS}, - {"cursyncup", PyCursesWindow_wcursyncup, METH_NOARGS}, + {"clear", PyCursesWindow_wclear, METH_NOARGS, + "clear($self, /)\n--\n\n" + "Clear the window and repaint it completely on the next refresh()."}, + {"clearok", PyCursesWindow_clearok, METH_VARARGS, + "clearok($self, flag, /)\n--\n\n" + "Clear the window on the next refresh() if flag is true."}, + {"clrtobot", PyCursesWindow_wclrtobot, METH_NOARGS, + "clrtobot($self, /)\n--\n\n" + "Erase from the cursor to the end of the window."}, + {"clrtoeol", PyCursesWindow_wclrtoeol, METH_NOARGS, + "clrtoeol($self, /)\n--\n\n" + "Erase from the cursor to the end of the line."}, + {"cursyncup", PyCursesWindow_wcursyncup, METH_NOARGS, + "cursyncup($self, /)\n--\n\n" + "Update the cursor position of all ancestor windows to match."}, _CURSES_WINDOW_DELCH_METHODDEF - {"deleteln", PyCursesWindow_wdeleteln, METH_NOARGS}, + {"deleteln", PyCursesWindow_wdeleteln, METH_NOARGS, + "deleteln($self, /)\n--\n\n" + "Delete the line under the cursor; move following lines up by one."}, _CURSES_WINDOW_DERWIN_METHODDEF _CURSES_WINDOW_ECHOCHAR_METHODDEF _CURSES_WINDOW_ENCLOSE_METHODDEF - {"erase", PyCursesWindow_werase, METH_NOARGS}, - {"getbegyx", PyCursesWindow_getbegyx, METH_NOARGS}, + {"erase", PyCursesWindow_werase, METH_NOARGS, + "erase($self, /)\n--\n\n" + "Clear the window."}, + {"getbegyx", PyCursesWindow_getbegyx, METH_NOARGS, + "getbegyx($self, /)\n--\n\n" + "Return a tuple (y, x) of the upper-left corner coordinates."}, _CURSES_WINDOW_GETBKGD_METHODDEF _CURSES_WINDOW_GETCH_METHODDEF _CURSES_WINDOW_GETKEY_METHODDEF _CURSES_WINDOW_GET_WCH_METHODDEF - {"getmaxyx", PyCursesWindow_getmaxyx, METH_NOARGS}, - {"getparyx", PyCursesWindow_getparyx, METH_NOARGS}, + {"getmaxyx", PyCursesWindow_getmaxyx, METH_NOARGS, + "getmaxyx($self, /)\n--\n\n" + "Return a tuple (y, x) of the window height and width."}, + {"getparyx", PyCursesWindow_getparyx, METH_NOARGS, + "getparyx($self, /)\n--\n\n" + "Return (y, x) relative to the parent window, or (-1, -1) if none."}, { "getstr", PyCursesWindow_getstr, METH_VARARGS, _curses_window_getstr__doc__ }, - {"getyx", PyCursesWindow_getyx, METH_NOARGS}, + {"getyx", PyCursesWindow_getyx, METH_NOARGS, + "getyx($self, /)\n--\n\n" + "Return a tuple (y, x) of the current cursor position."}, _CURSES_WINDOW_HLINE_METHODDEF - {"idcok", PyCursesWindow_idcok, METH_VARARGS}, - {"idlok", PyCursesWindow_idlok, METH_VARARGS}, + {"idcok", PyCursesWindow_idcok, METH_VARARGS, + "idcok($self, flag, /)\n--\n\n" + "Enable or disable the hardware insert/delete character feature."}, + {"idlok", PyCursesWindow_idlok, METH_VARARGS, + "idlok($self, flag, /)\n--\n\n" + "Enable or disable the hardware insert/delete line feature."}, #ifdef HAVE_CURSES_IMMEDOK - {"immedok", PyCursesWindow_immedok, METH_VARARGS}, + {"immedok", PyCursesWindow_immedok, METH_VARARGS, + "immedok($self, flag, /)\n--\n\n" + "If flag is true, refresh the window on every change to it."}, #endif _CURSES_WINDOW_INCH_METHODDEF _CURSES_WINDOW_INSCH_METHODDEF - {"insdelln", PyCursesWindow_winsdelln, METH_VARARGS}, - {"insertln", PyCursesWindow_winsertln, METH_NOARGS}, + {"insdelln", PyCursesWindow_winsdelln, METH_VARARGS, + "insdelln($self, nlines, /)\n--\n\n" + "Insert (nlines > 0) or delete (nlines < 0) lines above the cursor."}, + {"insertln", PyCursesWindow_winsertln, METH_NOARGS, + "insertln($self, /)\n--\n\n" + "Insert a blank line under the cursor; move following lines down."}, _CURSES_WINDOW_INSNSTR_METHODDEF _CURSES_WINDOW_INSSTR_METHODDEF { @@ -2977,40 +3009,78 @@ static PyMethodDef PyCursesWindow_methods[] = { _curses_window_instr__doc__ }, _CURSES_WINDOW_IS_LINETOUCHED_METHODDEF - {"is_wintouched", PyCursesWindow_is_wintouched, METH_NOARGS}, - {"keypad", PyCursesWindow_keypad, METH_VARARGS}, - {"leaveok", PyCursesWindow_leaveok, METH_VARARGS}, - {"move", PyCursesWindow_wmove, METH_VARARGS}, - {"mvderwin", PyCursesWindow_mvderwin, METH_VARARGS}, - {"mvwin", PyCursesWindow_mvwin, METH_VARARGS}, - {"nodelay", PyCursesWindow_nodelay, METH_VARARGS}, - {"notimeout", PyCursesWindow_notimeout, METH_VARARGS}, + {"is_wintouched", PyCursesWindow_is_wintouched, METH_NOARGS, + "is_wintouched($self, /)\n--\n\n" + "Return True if the window changed since the last refresh()."}, + {"keypad", PyCursesWindow_keypad, METH_VARARGS, + "keypad($self, flag, /)\n--\n\n" + "Interpret escape sequences for special keys if flag is true."}, + {"leaveok", PyCursesWindow_leaveok, METH_VARARGS, + "leaveok($self, flag, /)\n--\n\n" + "If flag is true, leave the cursor where the update leaves it."}, + {"move", PyCursesWindow_wmove, METH_VARARGS, + "move($self, new_y, new_x, /)\n--\n\n" + "Move the cursor to (new_y, new_x)."}, + {"mvderwin", PyCursesWindow_mvderwin, METH_VARARGS, + "mvderwin($self, y, x, /)\n--\n\n" + "Move the window inside its parent window."}, + {"mvwin", PyCursesWindow_mvwin, METH_VARARGS, + "mvwin($self, new_y, new_x, /)\n--\n\n" + "Move the window so its upper-left corner is at (new_y, new_x)."}, + {"nodelay", PyCursesWindow_nodelay, METH_VARARGS, + "nodelay($self, flag, /)\n--\n\n" + "If flag is true, getch() becomes non-blocking."}, + {"notimeout", PyCursesWindow_notimeout, METH_VARARGS, + "notimeout($self, flag, /)\n--\n\n" + "If flag is true, do not time out escape sequences."}, _CURSES_WINDOW_NOUTREFRESH_METHODDEF _CURSES_WINDOW_OVERLAY_METHODDEF _CURSES_WINDOW_OVERWRITE_METHODDEF _CURSES_WINDOW_PUTWIN_METHODDEF _CURSES_WINDOW_REDRAWLN_METHODDEF - {"redrawwin", PyCursesWindow_redrawwin, METH_NOARGS}, + {"redrawwin", PyCursesWindow_redrawwin, METH_NOARGS, + "redrawwin($self, /)\n--\n\n" + "Mark the entire window for redraw on the next refresh()."}, _CURSES_WINDOW_REFRESH_METHODDEF #ifndef STRICT_SYSV_CURSES - {"resize", PyCursesWindow_wresize, METH_VARARGS}, + {"resize", PyCursesWindow_wresize, METH_VARARGS, + "resize($self, nlines, ncols, /)\n--\n\n" + "Resize the window to nlines rows and ncols columns."}, #endif _CURSES_WINDOW_SCROLL_METHODDEF - {"scrollok", PyCursesWindow_scrollok, METH_VARARGS}, + {"scrollok", PyCursesWindow_scrollok, METH_VARARGS, + "scrollok($self, flag, /)\n--\n\n" + "Control whether the window scrolls when the cursor moves off it."}, _CURSES_WINDOW_SETSCRREG_METHODDEF - {"standend", PyCursesWindow_wstandend, METH_NOARGS}, - {"standout", PyCursesWindow_wstandout, METH_NOARGS}, + {"standend", PyCursesWindow_wstandend, METH_NOARGS, + "standend($self, /)\n--\n\n" + "Turn off the standout attribute."}, + {"standout", PyCursesWindow_wstandout, METH_NOARGS, + "standout($self, /)\n--\n\n" + "Turn on the A_STANDOUT attribute."}, {"subpad", _curses_window_subwin, METH_VARARGS, _curses_window_subwin__doc__}, _CURSES_WINDOW_SUBWIN_METHODDEF - {"syncdown", PyCursesWindow_wsyncdown, METH_NOARGS}, + {"syncdown", PyCursesWindow_wsyncdown, METH_NOARGS, + "syncdown($self, /)\n--\n\n" + "Touch each location changed in any ancestor of the window."}, #ifdef HAVE_CURSES_SYNCOK - {"syncok", PyCursesWindow_syncok, METH_VARARGS}, + {"syncok", PyCursesWindow_syncok, METH_VARARGS, + "syncok($self, flag, /)\n--\n\n" + "If flag is true, call syncup() on every change to the window."}, #endif - {"syncup", PyCursesWindow_wsyncup, METH_NOARGS}, - {"timeout", PyCursesWindow_wtimeout, METH_VARARGS}, + {"syncup", PyCursesWindow_wsyncup, METH_NOARGS, + "syncup($self, /)\n--\n\n" + "Touch locations in ancestors that changed in this window."}, + {"timeout", PyCursesWindow_wtimeout, METH_VARARGS, + "timeout($self, delay, /)\n--\n\n" + "Set blocking or non-blocking read behavior for the window."}, _CURSES_WINDOW_TOUCHLINE_METHODDEF - {"touchwin", PyCursesWindow_touchwin, METH_NOARGS}, - {"untouchwin", PyCursesWindow_untouchwin, METH_NOARGS}, + {"touchwin", PyCursesWindow_touchwin, METH_NOARGS, + "touchwin($self, /)\n--\n\n" + "Mark the whole window as changed."}, + {"untouchwin", PyCursesWindow_untouchwin, METH_NOARGS, + "untouchwin($self, /)\n--\n\n" + "Mark all lines in the window as unchanged since last refresh()."}, _CURSES_WINDOW_VLINE_METHODDEF {NULL, NULL} /* sentinel */ }; @@ -3127,11 +3197,17 @@ static PyType_Spec PyCursesWindow_Type_spec = { /*[clinic input] _curses.filter +Restrict screen updates to the current line. + +Must be called before initscr(). Afterwards curses confines the cursor +and screen updates to a single line, which is useful for enabling +character-at-a-time line editing without touching the rest of the +screen. [clinic start generated code]*/ static PyObject * _curses_filter_impl(PyObject *module) -/*[clinic end generated code: output=fb5b8a3642eb70b5 input=668c75a6992d3624]*/ +/*[clinic end generated code: output=fb5b8a3642eb70b5 input=e3c64d6ab2106132]*/ { /* not checking for PyCursesInitialised here since filter() must be called before initscr() */ @@ -4004,11 +4080,16 @@ _curses.intrflush flag: bool / +Control flushing of the output buffer when an interrupt key is pressed. + +If flag is true, pressing an interrupt key (interrupt, break, or quit) +flushes all output in the terminal driver queue. If flag is false, no +flushing is done. [clinic start generated code]*/ static PyObject * _curses_intrflush_impl(PyObject *module, int flag) -/*[clinic end generated code: output=c1986df35e999a0f input=c65fe2ef973fe40a]*/ +/*[clinic end generated code: output=c1986df35e999a0f input=66588c2bccc7e8fa]*/ { PyCursesStatefulInitialised(module); @@ -4525,11 +4606,14 @@ error: /*[clinic input] _curses.update_lines_cols +Update the LINES and COLS module variables. + +This is useful for detecting manual screen resize. [clinic start generated code]*/ static PyObject * _curses_update_lines_cols_impl(PyObject *module) -/*[clinic end generated code: output=423f2b1e63ed0f75 input=5f065ab7a28a5d90]*/ +/*[clinic end generated code: output=423f2b1e63ed0f75 input=1d8ea7c356b61a8b]*/ { if (!update_lines_cols(module)) { return NULL; diff --git a/Modules/clinic/_cursesmodule.c.h b/Modules/clinic/_cursesmodule.c.h index d46cc4cf768c..cab9b068a561 100644 --- a/Modules/clinic/_cursesmodule.c.h +++ b/Modules/clinic/_cursesmodule.c.h @@ -1844,7 +1844,13 @@ exit: PyDoc_STRVAR(_curses_filter__doc__, "filter($module, /)\n" "--\n" -"\n"); +"\n" +"Restrict screen updates to the current line.\n" +"\n" +"Must be called before initscr(). Afterwards curses confines the cursor\n" +"and screen updates to a single line, which is useful for enabling\n" +"character-at-a-time line editing without touching the rest of the\n" +"screen."); #define _CURSES_FILTER_METHODDEF \ {"filter", (PyCFunction)_curses_filter, METH_NOARGS, _curses_filter__doc__}, @@ -2917,7 +2923,12 @@ exit: PyDoc_STRVAR(_curses_intrflush__doc__, "intrflush($module, flag, /)\n" "--\n" -"\n"); +"\n" +"Control flushing of the output buffer when an interrupt key is pressed.\n" +"\n" +"If flag is true, pressing an interrupt key (interrupt, break, or quit)\n" +"flushes all output in the terminal driver queue. If flag is false, no\n" +"flushing is done."); #define _CURSES_INTRFLUSH_METHODDEF \ {"intrflush", (PyCFunction)_curses_intrflush, METH_O, _curses_intrflush__doc__}, @@ -3608,7 +3619,10 @@ exit: PyDoc_STRVAR(_curses_update_lines_cols__doc__, "update_lines_cols($module, /)\n" "--\n" -"\n"); +"\n" +"Update the LINES and COLS module variables.\n" +"\n" +"This is useful for detecting manual screen resize."); #define _CURSES_UPDATE_LINES_COLS_METHODDEF \ {"update_lines_cols", (PyCFunction)_curses_update_lines_cols, METH_NOARGS, _curses_update_lines_cols__doc__}, @@ -4472,4 +4486,4 @@ _curses_has_extended_color_support(PyObject *module, PyObject *Py_UNUSED(ignored #ifndef _CURSES_ASSUME_DEFAULT_COLORS_METHODDEF #define _CURSES_ASSUME_DEFAULT_COLORS_METHODDEF #endif /* !defined(_CURSES_ASSUME_DEFAULT_COLORS_METHODDEF) */ -/*[clinic end generated code: output=ab9b5057eeaf0f33 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=11ab7c93cbc13e75 input=a9049054013a1b77]*/