Skip to content

Commit 12add38

Browse files
serhiy-storchakaserhiy-storchaka
authored
gh-151623: Add missing curses docstrings and document intrflush() (#151632)
1 parent f551705 commit 12add38

3 files changed

Lines changed: 147 additions & 42 deletions

File tree

‎Doc/library/curses.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -330,6 +330,13 @@ The module :mod:`!curses` defines the following functions:
330330
cause the interpreter to exit.
331331

332332

333+
.. function:: intrflush(flag)
334+
335+
If *flag* is ``True``, pressing an interrupt key (interrupt, break, or quit)
336+
will flush all output in the terminal driver queue. If *flag* is ``False``,
337+
no flushing is done.
338+
339+
333340
.. function:: is_term_resized(nlines, ncols)
334341

335342
Return ``True`` if :func:`resize_term` would modify the window structure,

‎Modules/_cursesmodule.c‎

Lines changed: 122 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2937,80 +2937,150 @@ static PyMethodDef PyCursesWindow_methods[] = {
29372937
_CURSES_WINDOW_BKGDSET_METHODDEF
29382938
_CURSES_WINDOW_BORDER_METHODDEF
29392939
_CURSES_WINDOW_BOX_METHODDEF
2940-
{"clear", PyCursesWindow_wclear, METH_NOARGS},
2941-
{"clearok", PyCursesWindow_clearok, METH_VARARGS},
2942-
{"clrtobot", PyCursesWindow_wclrtobot, METH_NOARGS},
2943-
{"clrtoeol", PyCursesWindow_wclrtoeol, METH_NOARGS},
2944-
{"cursyncup", PyCursesWindow_wcursyncup, METH_NOARGS},
2940+
{"clear", PyCursesWindow_wclear, METH_NOARGS,
2941+
"clear($self, /)\n--\n\n"
2942+
"Clear the window and repaint it completely on the next refresh()."},
2943+
{"clearok", PyCursesWindow_clearok, METH_VARARGS,
2944+
"clearok($self, flag, /)\n--\n\n"
2945+
"Clear the window on the next refresh() if flag is true."},
2946+
{"clrtobot", PyCursesWindow_wclrtobot, METH_NOARGS,
2947+
"clrtobot($self, /)\n--\n\n"
2948+
"Erase from the cursor to the end of the window."},
2949+
{"clrtoeol", PyCursesWindow_wclrtoeol, METH_NOARGS,
2950+
"clrtoeol($self, /)\n--\n\n"
2951+
"Erase from the cursor to the end of the line."},
2952+
{"cursyncup", PyCursesWindow_wcursyncup, METH_NOARGS,
2953+
"cursyncup($self, /)\n--\n\n"
2954+
"Update the cursor position of all ancestor windows to match."},
29452955
_CURSES_WINDOW_DELCH_METHODDEF
2946-
{"deleteln", PyCursesWindow_wdeleteln, METH_NOARGS},
2956+
{"deleteln", PyCursesWindow_wdeleteln, METH_NOARGS,
2957+
"deleteln($self, /)\n--\n\n"
2958+
"Delete the line under the cursor; move following lines up by one."},
29472959
_CURSES_WINDOW_DERWIN_METHODDEF
29482960
_CURSES_WINDOW_ECHOCHAR_METHODDEF
29492961
_CURSES_WINDOW_ENCLOSE_METHODDEF
2950-
{"erase", PyCursesWindow_werase, METH_NOARGS},
2951-
{"getbegyx", PyCursesWindow_getbegyx, METH_NOARGS},
2962+
{"erase", PyCursesWindow_werase, METH_NOARGS,
2963+
"erase($self, /)\n--\n\n"
2964+
"Clear the window."},
2965+
{"getbegyx", PyCursesWindow_getbegyx, METH_NOARGS,
2966+
"getbegyx($self, /)\n--\n\n"
2967+
"Return a tuple (y, x) of the upper-left corner coordinates."},
29522968
_CURSES_WINDOW_GETBKGD_METHODDEF
29532969
_CURSES_WINDOW_GETCH_METHODDEF
29542970
_CURSES_WINDOW_GETKEY_METHODDEF
29552971
_CURSES_WINDOW_GET_WCH_METHODDEF
2956-
{"getmaxyx", PyCursesWindow_getmaxyx, METH_NOARGS},
2957-
{"getparyx", PyCursesWindow_getparyx, METH_NOARGS},
2972+
{"getmaxyx", PyCursesWindow_getmaxyx, METH_NOARGS,
2973+
"getmaxyx($self, /)\n--\n\n"
2974+
"Return a tuple (y, x) of the window height and width."},
2975+
{"getparyx", PyCursesWindow_getparyx, METH_NOARGS,
2976+
"getparyx($self, /)\n--\n\n"
2977+
"Return (y, x) relative to the parent window, or (-1, -1) if none."},
29582978
{
29592979
"getstr", PyCursesWindow_getstr, METH_VARARGS,
29602980
_curses_window_getstr__doc__
29612981
},
2962-
{"getyx", PyCursesWindow_getyx, METH_NOARGS},
2982+
{"getyx", PyCursesWindow_getyx, METH_NOARGS,
2983+
"getyx($self, /)\n--\n\n"
2984+
"Return a tuple (y, x) of the current cursor position."},
29632985
_CURSES_WINDOW_HLINE_METHODDEF
2964-
{"idcok", PyCursesWindow_idcok, METH_VARARGS},
2965-
{"idlok", PyCursesWindow_idlok, METH_VARARGS},
2986+
{"idcok", PyCursesWindow_idcok, METH_VARARGS,
2987+
"idcok($self, flag, /)\n--\n\n"
2988+
"Enable or disable the hardware insert/delete character feature."},
2989+
{"idlok", PyCursesWindow_idlok, METH_VARARGS,
2990+
"idlok($self, flag, /)\n--\n\n"
2991+
"Enable or disable the hardware insert/delete line feature."},
29662992
#ifdef HAVE_CURSES_IMMEDOK
2967-
{"immedok", PyCursesWindow_immedok, METH_VARARGS},
2993+
{"immedok", PyCursesWindow_immedok, METH_VARARGS,
2994+
"immedok($self, flag, /)\n--\n\n"
2995+
"If flag is true, refresh the window on every change to it."},
29682996
#endif
29692997
_CURSES_WINDOW_INCH_METHODDEF
29702998
_CURSES_WINDOW_INSCH_METHODDEF
2971-
{"insdelln", PyCursesWindow_winsdelln, METH_VARARGS},
2972-
{"insertln", PyCursesWindow_winsertln, METH_NOARGS},
2999+
{"insdelln", PyCursesWindow_winsdelln, METH_VARARGS,
3000+
"insdelln($self, nlines, /)\n--\n\n"
3001+
"Insert (nlines > 0) or delete (nlines < 0) lines above the cursor."},
3002+
{"insertln", PyCursesWindow_winsertln, METH_NOARGS,
3003+
"insertln($self, /)\n--\n\n"
3004+
"Insert a blank line under the cursor; move following lines down."},
29733005
_CURSES_WINDOW_INSNSTR_METHODDEF
29743006
_CURSES_WINDOW_INSSTR_METHODDEF
29753007
{
29763008
"instr", PyCursesWindow_instr, METH_VARARGS,
29773009
_curses_window_instr__doc__
29783010
},
29793011
_CURSES_WINDOW_IS_LINETOUCHED_METHODDEF
2980-
{"is_wintouched", PyCursesWindow_is_wintouched, METH_NOARGS},
2981-
{"keypad", PyCursesWindow_keypad, METH_VARARGS},
2982-
{"leaveok", PyCursesWindow_leaveok, METH_VARARGS},
2983-
{"move", PyCursesWindow_wmove, METH_VARARGS},
2984-
{"mvderwin", PyCursesWindow_mvderwin, METH_VARARGS},
2985-
{"mvwin", PyCursesWindow_mvwin, METH_VARARGS},
2986-
{"nodelay", PyCursesWindow_nodelay, METH_VARARGS},
2987-
{"notimeout", PyCursesWindow_notimeout, METH_VARARGS},
3012+
{"is_wintouched", PyCursesWindow_is_wintouched, METH_NOARGS,
3013+
"is_wintouched($self, /)\n--\n\n"
3014+
"Return True if the window changed since the last refresh()."},
3015+
{"keypad", PyCursesWindow_keypad, METH_VARARGS,
3016+
"keypad($self, flag, /)\n--\n\n"
3017+
"Interpret escape sequences for special keys if flag is true."},
3018+
{"leaveok", PyCursesWindow_leaveok, METH_VARARGS,
3019+
"leaveok($self, flag, /)\n--\n\n"
3020+
"If flag is true, leave the cursor where the update leaves it."},
3021+
{"move", PyCursesWindow_wmove, METH_VARARGS,
3022+
"move($self, new_y, new_x, /)\n--\n\n"
3023+
"Move the cursor to (new_y, new_x)."},
3024+
{"mvderwin", PyCursesWindow_mvderwin, METH_VARARGS,
3025+
"mvderwin($self, y, x, /)\n--\n\n"
3026+
"Move the window inside its parent window."},
3027+
{"mvwin", PyCursesWindow_mvwin, METH_VARARGS,
3028+
"mvwin($self, new_y, new_x, /)\n--\n\n"
3029+
"Move the window so its upper-left corner is at (new_y, new_x)."},
3030+
{"nodelay", PyCursesWindow_nodelay, METH_VARARGS,
3031+
"nodelay($self, flag, /)\n--\n\n"
3032+
"If flag is true, getch() becomes non-blocking."},
3033+
{"notimeout", PyCursesWindow_notimeout, METH_VARARGS,
3034+
"notimeout($self, flag, /)\n--\n\n"
3035+
"If flag is true, do not time out escape sequences."},
29883036
_CURSES_WINDOW_NOUTREFRESH_METHODDEF
29893037
_CURSES_WINDOW_OVERLAY_METHODDEF
29903038
_CURSES_WINDOW_OVERWRITE_METHODDEF
29913039
_CURSES_WINDOW_PUTWIN_METHODDEF
29923040
_CURSES_WINDOW_REDRAWLN_METHODDEF
2993-
{"redrawwin", PyCursesWindow_redrawwin, METH_NOARGS},
3041+
{"redrawwin", PyCursesWindow_redrawwin, METH_NOARGS,
3042+
"redrawwin($self, /)\n--\n\n"
3043+
"Mark the entire window for redraw on the next refresh()."},
29943044
_CURSES_WINDOW_REFRESH_METHODDEF
29953045
#ifndef STRICT_SYSV_CURSES
2996-
{"resize", PyCursesWindow_wresize, METH_VARARGS},
3046+
{"resize", PyCursesWindow_wresize, METH_VARARGS,
3047+
"resize($self, nlines, ncols, /)\n--\n\n"
3048+
"Resize the window to nlines rows and ncols columns."},
29973049
#endif
29983050
_CURSES_WINDOW_SCROLL_METHODDEF
2999-
{"scrollok", PyCursesWindow_scrollok, METH_VARARGS},
3051+
{"scrollok", PyCursesWindow_scrollok, METH_VARARGS,
3052+
"scrollok($self, flag, /)\n--\n\n"
3053+
"Control whether the window scrolls when the cursor moves off it."},
30003054
_CURSES_WINDOW_SETSCRREG_METHODDEF
3001-
{"standend", PyCursesWindow_wstandend, METH_NOARGS},
3002-
{"standout", PyCursesWindow_wstandout, METH_NOARGS},
3055+
{"standend", PyCursesWindow_wstandend, METH_NOARGS,
3056+
"standend($self, /)\n--\n\n"
3057+
"Turn off the standout attribute."},
3058+
{"standout", PyCursesWindow_wstandout, METH_NOARGS,
3059+
"standout($self, /)\n--\n\n"
3060+
"Turn on the A_STANDOUT attribute."},
30033061
{"subpad", _curses_window_subwin, METH_VARARGS, _curses_window_subwin__doc__},
30043062
_CURSES_WINDOW_SUBWIN_METHODDEF
3005-
{"syncdown", PyCursesWindow_wsyncdown, METH_NOARGS},
3063+
{"syncdown", PyCursesWindow_wsyncdown, METH_NOARGS,
3064+
"syncdown($self, /)\n--\n\n"
3065+
"Touch each location changed in any ancestor of the window."},
30063066
#ifdef HAVE_CURSES_SYNCOK
3007-
{"syncok", PyCursesWindow_syncok, METH_VARARGS},
3067+
{"syncok", PyCursesWindow_syncok, METH_VARARGS,
3068+
"syncok($self, flag, /)\n--\n\n"
3069+
"If flag is true, call syncup() on every change to the window."},
30083070
#endif
3009-
{"syncup", PyCursesWindow_wsyncup, METH_NOARGS},
3010-
{"timeout", PyCursesWindow_wtimeout, METH_VARARGS},
3071+
{"syncup", PyCursesWindow_wsyncup, METH_NOARGS,
3072+
"syncup($self, /)\n--\n\n"
3073+
"Touch locations in ancestors that changed in this window."},
3074+
{"timeout", PyCursesWindow_wtimeout, METH_VARARGS,
3075+
"timeout($self, delay, /)\n--\n\n"
3076+
"Set blocking or non-blocking read behavior for the window."},
30113077
_CURSES_WINDOW_TOUCHLINE_METHODDEF
3012-
{"touchwin", PyCursesWindow_touchwin, METH_NOARGS},
3013-
{"untouchwin", PyCursesWindow_untouchwin, METH_NOARGS},
3078+
{"touchwin", PyCursesWindow_touchwin, METH_NOARGS,
3079+
"touchwin($self, /)\n--\n\n"
3080+
"Mark the whole window as changed."},
3081+
{"untouchwin", PyCursesWindow_untouchwin, METH_NOARGS,
3082+
"untouchwin($self, /)\n--\n\n"
3083+
"Mark all lines in the window as unchanged since last refresh()."},
30143084
_CURSES_WINDOW_VLINE_METHODDEF
30153085
{NULL, NULL} /* sentinel */
30163086
};
@@ -3127,11 +3197,17 @@ static PyType_Spec PyCursesWindow_Type_spec = {
31273197
/*[clinic input]
31283198
_curses.filter
31293199
3200+
Restrict screen updates to the current line.
3201+
3202+
Must be called before initscr(). Afterwards curses confines the cursor
3203+
and screen updates to a single line, which is useful for enabling
3204+
character-at-a-time line editing without touching the rest of the
3205+
screen.
31303206
[clinic start generated code]*/
31313207

31323208
static PyObject *
31333209
_curses_filter_impl(PyObject *module)
3134-
/*[clinic end generated code: output=fb5b8a3642eb70b5 input=668c75a6992d3624]*/
3210+
/*[clinic end generated code: output=fb5b8a3642eb70b5 input=e3c64d6ab2106132]*/
31353211
{
31363212
/* not checking for PyCursesInitialised here since filter() must
31373213
be called before initscr() */
@@ -4004,11 +4080,16 @@ _curses.intrflush
40044080
flag: bool
40054081
/
40064082
4083+
Control flushing of the output buffer when an interrupt key is pressed.
4084+
4085+
If flag is true, pressing an interrupt key (interrupt, break, or quit)
4086+
flushes all output in the terminal driver queue. If flag is false, no
4087+
flushing is done.
40074088
[clinic start generated code]*/
40084089

40094090
static PyObject *
40104091
_curses_intrflush_impl(PyObject *module, int flag)
4011-
/*[clinic end generated code: output=c1986df35e999a0f input=c65fe2ef973fe40a]*/
4092+
/*[clinic end generated code: output=c1986df35e999a0f input=66588c2bccc7e8fa]*/
40124093
{
40134094
PyCursesStatefulInitialised(module);
40144095

@@ -4525,11 +4606,14 @@ update_lines_cols(PyObject *private_module)
45254606
/*[clinic input]
45264607
_curses.update_lines_cols
45274608
4609+
Update the LINES and COLS module variables.
4610+
4611+
This is useful for detecting manual screen resize.
45284612
[clinic start generated code]*/
45294613

45304614
static PyObject *
45314615
_curses_update_lines_cols_impl(PyObject *module)
4532-
/*[clinic end generated code: output=423f2b1e63ed0f75 input=5f065ab7a28a5d90]*/
4616+
/*[clinic end generated code: output=423f2b1e63ed0f75 input=1d8ea7c356b61a8b]*/
45334617
{
45344618
if (!update_lines_cols(module)) {
45354619
return NULL;

‎Modules/clinic/_cursesmodule.c.h‎

Lines changed: 18 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)