Skip to content

[3.15] gh-151623: Add missing curses docstrings and document intrflush() (GH-151632) #151641

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
serhiy-storchaka merged 1 commit into from
Jun 18, 2026
+147 −42
Merged

[3.15] gh-151623: Add missing curses docstrings and document intrflush() (GH-151632) #151641

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions Doc/library/curses.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
160 changes: 122 additions & 38 deletions Modules/_cursesmodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2937,80 +2937,150 @@ 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
{
"instr", PyCursesWindow_instr, METH_VARARGS,
_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 */
};
Expand Down Expand Up @@ -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() */
Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -4525,11 +4606,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;
Expand Down
22 changes: 18 additions & 4 deletions Modules/clinic/_cursesmodule.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading