https://github.com/python/cpython/commit/1ed98a6b5155dd239d35f3c9dd35477feded9e1c
commit: 1ed98a6b5155dd239d35f3c9dd35477feded9e1c
branch: 3.14
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2026-06-18T11:20:45Z
summary:
[3.14] gh-151623: Add missing curses docstrings and document intrflush()
(GH-151632) (GH-151642)
(cherry picked from commit 12add3822f458a3e107dff4176b4c4b991764ea7)
files:
M Doc/library/curses.rst
M Modules/_cursesmodule.c
M Modules/clinic/_cursesmodule.c.h
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index c252b453386a45..3d037ea7b45594 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -333,6 +333,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 03bb8cae681127..4f3c4174a20d05 100644
--- a/Modules/_cursesmodule.c
+++ b/Modules/_cursesmodule.c
@@ -2688,39 +2688,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
{
@@ -2728,40 +2760,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 */
};
@@ -2849,11 +2919,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() */
@@ -3720,11 +3796,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);
@@ -4236,11 +4317,14 @@ update_lines_cols(PyObject *private_module)
/*[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 6e05744a78dff7..18c1a3229e9330 100644
--- a/Modules/clinic/_cursesmodule.c.h
+++ b/Modules/clinic/_cursesmodule.c.h
@@ -1859,7 +1859,13 @@ _curses_window_vline(PyObject *self, PyObject *args)
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 @@ _curses_set_tabsize(PyObject *module, PyObject *arg)
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__},
@@ -3593,7 +3604,10 @@ _curses_qiflush(PyObject *module, PyObject *const *args,
Py_ssize_t nargs)
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__},
@@ -4457,4 +4471,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=1078826fefbbc07a input=a9049054013a1b77]*/
+/*[clinic end generated code: output=e0fb3129157f3af8 input=a9049054013a1b77]*/
_______________________________________________
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]
