https://github.com/python/cpython/commit/6a9dbffa524ccc5486153177fea2f4ac7aca1e52
commit: 6a9dbffa524ccc5486153177fea2f4ac7aca1e52
branch: 3.15
author: Serhiy Storchaka <[email protected]>
committer: hugovk <[email protected]>
date: 2026-08-27T15:52:03+03:00
summary:
[3.15] gh-156234: Fix and rewrite the curses documentation on reading
(GH-156235) (#156279)
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 d1545a188f25b2a..f87107f395a8c4a 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -27,6 +27,8 @@ Linux and the BSD variants of Unix.
Whenever the documentation mentions a *character* it can be specified
as an integer, a one-character Unicode string or a one-byte byte string.
+ An integer is the code of a single encoded byte, optionally combined with
+ attributes and a color pair, as returned by :meth:`window.inch`.
Whenever the documentation mentions a *character string* it can be specified
as a Unicode string or a byte string.
@@ -502,8 +504,8 @@ The module :mod:`!curses` defines the following functions:
.. function:: putp(str)
Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified
- terminfo capability for the current terminal. Note that the output of
:func:`putp`
- always goes to standard output.
+ terminfo capability, a bytes object, for the current terminal.
+ Note that the output of :func:`putp` always goes to standard output.
:func:`setupterm` (or :func:`initscr`) must be called first.
@@ -674,7 +676,7 @@ The module :mod:`!curses` defines the following functions:
.. function:: tparm(str[, ...])
Instantiate the bytes object *str* with the supplied parameters, where
*str* should
- be a parameterized string obtained from the terminfo database. For example,
+ be a parameterized byte string obtained from the terminfo database. For
example,
``tparm(tigetstr("cup"), 5, 3)`` could result in ``b'\033[6;4H'``, the exact
result depending on terminal type. Up to nine integer parameters may be
supplied.
@@ -695,7 +697,8 @@ The module :mod:`!curses` defines the following functions:
.. function:: unctrl(ch)
- Return a bytes object which is a printable representation of the character
*ch*.
+ Return a bytes object which is a printable representation of the character
*ch*;
+ any attributes and color pair are ignored.
Control characters are represented as a caret followed by the character, for
example as ``b'^C'``. Printing characters are left as they are.
@@ -704,6 +707,9 @@ The module :mod:`!curses` defines the following functions:
Push *ch* so the next :meth:`~window.getch` will return it.
+ *ch* may be an integer (a key code or the code of an encoded byte), a byte,
+ or a string of length 1 which encodes to a single byte.
+
.. note::
Only one *ch* can be pushed before :meth:`!getch` is called.
@@ -721,6 +727,9 @@ The module :mod:`!curses` defines the following functions:
Push *ch* so the next :meth:`~window.get_wch` will return it.
+ *ch* may be an integer (a character code, not a key code) or a string of
+ length 1.
+
.. note::
Only one *ch* can be pushed before :meth:`!get_wch` is called.
@@ -1001,27 +1010,58 @@ Window objects
.. method:: window.getch([y, x])
- Get a character. Note that the integer returned does *not* have to be in
ASCII
- range: function keys, keypad keys and so on are represented by numbers
higher
- than 255. In no-delay mode, return ``-1`` if there is no input, otherwise
- wait until a key is pressed.
+ Read a key press, after moving the cursor to *y*, *x* if specified,
+ and return it as an integer.
+ The window is refreshed first if it is not a pad and was modified since
+ the last refresh.
+ Wait until a key is pressed, or return ``-1`` if the read is non-blocking
+ or times out (see :meth:`nodelay` and :meth:`timeout`).
+
+ An ordinary key is returned as the code of a single byte of its encoding
+ in the current locale,
+ so a character encoded with several bytes takes several calls.
+ For example, in a UTF-8 locale ``'é'`` is read as ``195``, then ``169``.
+ Use :meth:`get_wch` to read it as a single character.
+
+ In keypad mode (see :meth:`keypad`) function keys and other special keys
+ are returned as one of the :ref:`KEY_* constants <curses-key-constants>`,
+ which cannot be mistaken for an ordinary key.
+ Otherwise, or if their escape sequence does not arrive in time
+ (see :meth:`notimeout` and :func:`set_escdelay`),
+ their bytes are returned one at a time.
+
+ In echo mode (see :func:`echo`) the key is added to the window as by
+ :meth:`addch`; special keys are not echoed.
.. method:: window.get_wch([y, x])
- Get a wide character. Return a character for most keys, or an integer for
- function keys, keypad keys, and other special keys.
- In no-delay mode, raise an exception if there is no input.
+ Read a key press, after moving the cursor to *y*, *x* if specified,
+ and return it as a one-character :class:`str`.
+ The window is refreshed first if it is not a pad and was modified since
+ the last refresh.
+ Wait until a key is pressed, or raise :exc:`error` if the read is
+ non-blocking or times out (see :meth:`nodelay` and :meth:`timeout`).
+
+ In keypad mode (see :meth:`keypad`) function keys and other special keys
+ are returned as one of the :ref:`KEY_* constants <curses-key-constants>`,
+ an integer.
+ Otherwise, or if their escape sequence does not arrive in time
+ (see :meth:`notimeout` and :func:`set_escdelay`),
+ their characters are returned one at a time.
+
+ In echo mode (see :func:`echo`) the key is added to the window as by
+ :meth:`addch`; special keys are not echoed.
.. versionadded:: 3.3
.. method:: window.getkey([y, x])
- Get a character, returning a string instead of an integer, as :meth:`getch`
- does. Function keys, keypad keys and other special keys return a multibyte
- string containing the key name. In no-delay mode, raise an exception if
- there is no input.
+ Read a key press as :meth:`getch` does, but return it as a :class:`str`:
+ an ordinary key as a one-character string, the byte decoded as Latin-1,
+ and a special key as its name, such as ``'KEY_UP'`` (see :func:`keyname`).
+ Raise :exc:`error` instead of returning ``-1`` if there is no input.
.. method:: window.getmaxyx()
@@ -1041,8 +1081,11 @@ Window objects
window.getstr(y, x)
window.getstr(y, x, n)
- Read a bytes object from the user, with primitive line editing capacity.
- At most *n* characters are read;
+ Read a line of input from the user, with primitive line editing capacity,
+ after moving the cursor to *y*, *x* if specified.
+ Return it as a bytes object, in the encoding of the current locale
+ and without the terminating newline.
+ At most *n* bytes are read;
*n* defaults to and cannot exceed 2047.
.. versionchanged:: 3.14
@@ -1144,12 +1187,11 @@ Window objects
.. method:: window.instr([n])
window.instr(y, x[, n])
- Return a bytes object of characters, extracted from the window starting at
the
- current cursor position, or at *y*, *x* if specified, and stopping at the
end
- of the line. Attributes and color information are stripped
- from the characters. If *n* is specified, :meth:`instr` returns a string
- at most *n* characters long (exclusive of the trailing NUL).
- The maximum value for *n* is 2047.
+ Read the text of the window from the current cursor position,
+ or from *y*, *x* if specified, to the end of the line,
+ and return it as a bytes object, in the encoding of the current locale.
+ Attributes and color pairs are stripped.
+ At most *n* bytes are read; *n* defaults to and cannot exceed 2047.
.. versionchanged:: 3.14
The maximum value for *n* was increased from 1023 to 2047.
@@ -1173,6 +1215,8 @@ Window objects
If *flag* is ``True``, escape sequences generated by some keys (keypad,
function keys)
will be interpreted by :mod:`!curses`. If *flag* is ``False``, escape
sequences will be
left as is in the input stream.
+ Keypad mode is disabled by default, but :func:`wrapper` enables it for the
+ main window.
.. method:: window.leaveok(flag)
@@ -1525,6 +1569,8 @@ by some methods.
| | color-pair field information |
+-------------------------+-------------------------------+
+.. _curses-key-constants:
+
Keys are referred to by integer constants with names starting with ``KEY_``.
The exact keycaps available are system dependent.
diff --git a/Modules/_cursesmodule.c b/Modules/_cursesmodule.c
index 82c8e642a51154f..f7ec3d24b03abd5 100644
--- a/Modules/_cursesmodule.c
+++ b/Modules/_cursesmodule.c
@@ -1747,18 +1747,25 @@ _curses.window.getch
]
/
-Get a character code from terminal keyboard.
+Read a key press and return it as an integer.
-The integer returned does not have to be in ASCII range: function
-keys, keypad keys and so on return numbers higher than 256. In
-no-delay mode, -1 is returned if there is no input, else getch()
-waits until a key is pressed.
+Wait until a key is pressed, or return -1 if the read is
+non-blocking or times out.
+
+An ordinary key is returned as the code of a single byte of its
+encoding in the current locale, so a character encoded with several
+bytes takes several calls. Use get_wch() to read it as a single
+character.
+
+In keypad mode function keys and other special keys are returned as
+one of the KEY_* constants, which cannot be mistaken for an ordinary
+key. Otherwise their bytes are returned one at a time.
[clinic start generated code]*/
static PyObject *
_curses_window_getch_impl(PyCursesWindowObject *self, int group_right_1,
int y, int x)
-/*[clinic end generated code: output=e1639e87d545e676 input=0dc5ff40e079787a]*/
+/*[clinic end generated code: output=e1639e87d545e676 input=882ddab9b41afbbd]*/
{
int rtn;
@@ -1795,18 +1802,18 @@ _curses.window.getkey
]
/
-Get a character (string) from terminal keyboard.
+Read a key press and return it as a str.
-Returning a string instead of an integer, as getch() does. Function
-keys, keypad keys and other special keys return a multibyte string
-containing the key name. In no-delay mode, an exception is raised
-if there is no input.
+Read as getch() does, but return an ordinary key as a one-character
+string, the byte decoded as Latin-1, and a special key as its name,
+such as 'KEY_UP'. Raise curses.error instead of returning -1 if
+there is no input.
[clinic start generated code]*/
static PyObject *
_curses_window_getkey_impl(PyCursesWindowObject *self, int group_right_1,
int y, int x)
-/*[clinic end generated code: output=8490a182db46b10f input=bd24a7da1ed9c73b]*/
+/*[clinic end generated code: output=8490a182db46b10f input=f054cf034c69e879]*/
{
int rtn;
@@ -1851,16 +1858,20 @@ _curses.window.get_wch
]
/
-Get a wide character from terminal keyboard.
+Read a key press and return it as a one-character str.
+
+Wait until a key is pressed, or raise curses.error if the read is
+non-blocking or times out.
-Return a character for most keys, or an integer for function keys,
-keypad keys, and other special keys.
+In keypad mode function keys and other special keys are returned as
+one of the KEY_* constants, an integer. Otherwise their characters
+are returned one at a time.
[clinic start generated code]*/
static PyObject *
_curses_window_get_wch_impl(PyCursesWindowObject *self, int group_right_1,
int y, int x)
-/*[clinic end generated code: output=9f4f86e91fe50ef3 input=dd7e5367fb49dc48]*/
+/*[clinic end generated code: output=9f4f86e91fe50ef3 input=77eb2da426ebe71f]*/
{
int ct;
wint_t rtn;
@@ -1928,14 +1939,14 @@ curses_clinic_parse_optional_xy_n(PyObject *args,
PyDoc_STRVAR(_curses_window_getstr__doc__,
"getstr([[y, x,] n=2047])\n"
-"Read a string from the user, with primitive line editing capacity.\n"
+"Read a line of input and return it as a bytes object.\n"
"\n"
" y\n"
" Y-coordinate.\n"
" x\n"
" X-coordinate.\n"
" n\n"
-" Maximal number of characters.");
+" Maximal number of bytes.");
static PyObject *
PyCursesWindow_getstr(PyObject *op, PyObject *args)
@@ -2180,21 +2191,19 @@ _curses_window_inch_impl(PyCursesWindowObject *self,
int group_right_1,
PyDoc_STRVAR(_curses_window_instr__doc__,
"instr([y, x,] n=2047)\n"
-"Return a string of characters, extracted from the window.\n"
+"Return the text of the window as a bytes object.\n"
"\n"
" y\n"
" Y-coordinate.\n"
" x\n"
" X-coordinate.\n"
" n\n"
-" Maximal number of characters.\n"
+" Maximal number of bytes.\n"
"\n"
-"Return a string of characters, extracted from the window starting\n"
-"at the current cursor position, or at y, x if specified, and\n"
-"stopping at the end of the line. Attributes and color\n"
-"information are stripped from the characters. If n is specified,\n"
-"instr() returns a string at most n characters long (exclusive of\n"
-"the trailing NUL).");
+"Read from the current cursor position, or from y, x if specified, to\n"
+"the end of the line, and return the text in the encoding of the\n"
+"current locale, with attributes and color pairs stripped. At most n\n"
+"bytes are read.");
static PyObject *
PyCursesWindow_instr(PyObject *op, PyObject *args)
@@ -5109,15 +5118,16 @@ _curses.unctrl
ch: object
/
-Return a string which is a printable representation of the character ch.
+Return a bytes object which is a printable representation of ch.
-Control characters are displayed as a caret followed by the character,
-for example as ^C. Printing characters are left as they are.
+Control characters are displayed as a caret followed by the
+character, for example as ^C. Printing characters are left as they
+are. Any attributes and color pair are ignored.
[clinic start generated code]*/
static PyObject *
_curses_unctrl(PyObject *module, PyObject *ch)
-/*[clinic end generated code: output=8e07fafc430c9434 input=cd1e35e16cd1ace4]*/
+/*[clinic end generated code: output=8e07fafc430c9434 input=6732d59733d3ed5b]*/
{
chtype ch_;
diff --git a/Modules/clinic/_cursesmodule.c.h b/Modules/clinic/_cursesmodule.c.h
index 0d2237241260eb6..ddc491f0d4a5b4c 100644
--- a/Modules/clinic/_cursesmodule.c.h
+++ b/Modules/clinic/_cursesmodule.c.h
@@ -748,17 +748,24 @@ _curses_window_getbkgd(PyObject *self, PyObject
*Py_UNUSED(ignored))
PyDoc_STRVAR(_curses_window_getch__doc__,
"getch([y, x])\n"
-"Get a character code from terminal keyboard.\n"
+"Read a key press and return it as an integer.\n"
"\n"
" y\n"
" Y-coordinate.\n"
" x\n"
" X-coordinate.\n"
"\n"
-"The integer returned does not have to be in ASCII range: function\n"
-"keys, keypad keys and so on return numbers higher than 256. In\n"
-"no-delay mode, -1 is returned if there is no input, else getch()\n"
-"waits until a key is pressed.");
+"Wait until a key is pressed, or return -1 if the read is\n"
+"non-blocking or times out.\n"
+"\n"
+"An ordinary key is returned as the code of a single byte of its\n"
+"encoding in the current locale, so a character encoded with several\n"
+"bytes takes several calls. Use get_wch() to read it as a single\n"
+"character.\n"
+"\n"
+"In keypad mode function keys and other special keys are returned as\n"
+"one of the KEY_* constants, which cannot be mistaken for an ordinary\n"
+"key. Otherwise their bytes are returned one at a time.");
#define _CURSES_WINDOW_GETCH_METHODDEF \
{"getch", (PyCFunction)_curses_window_getch, METH_VARARGS,
_curses_window_getch__doc__},
@@ -796,17 +803,17 @@ _curses_window_getch(PyObject *self, PyObject *args)
PyDoc_STRVAR(_curses_window_getkey__doc__,
"getkey([y, x])\n"
-"Get a character (string) from terminal keyboard.\n"
+"Read a key press and return it as a str.\n"
"\n"
" y\n"
" Y-coordinate.\n"
" x\n"
" X-coordinate.\n"
"\n"
-"Returning a string instead of an integer, as getch() does. Function\n"
-"keys, keypad keys and other special keys return a multibyte string\n"
-"containing the key name. In no-delay mode, an exception is raised\n"
-"if there is no input.");
+"Read as getch() does, but return an ordinary key as a one-character\n"
+"string, the byte decoded as Latin-1, and a special key as its name,\n"
+"such as \'KEY_UP\'. Raise curses.error instead of returning -1 if\n"
+"there is no input.");
#define _CURSES_WINDOW_GETKEY_METHODDEF \
{"getkey", (PyCFunction)_curses_window_getkey, METH_VARARGS,
_curses_window_getkey__doc__},
@@ -846,15 +853,19 @@ _curses_window_getkey(PyObject *self, PyObject *args)
PyDoc_STRVAR(_curses_window_get_wch__doc__,
"get_wch([y, x])\n"
-"Get a wide character from terminal keyboard.\n"
+"Read a key press and return it as a one-character str.\n"
"\n"
" y\n"
" Y-coordinate.\n"
" x\n"
" X-coordinate.\n"
"\n"
-"Return a character for most keys, or an integer for function keys,\n"
-"keypad keys, and other special keys.");
+"Wait until a key is pressed, or raise curses.error if the read is\n"
+"non-blocking or times out.\n"
+"\n"
+"In keypad mode function keys and other special keys are returned as\n"
+"one of the KEY_* constants, an integer. Otherwise their characters\n"
+"are returned one at a time.");
#define _CURSES_WINDOW_GET_WCH_METHODDEF \
{"get_wch", (PyCFunction)_curses_window_get_wch, METH_VARARGS,
_curses_window_get_wch__doc__},
@@ -4232,10 +4243,11 @@ PyDoc_STRVAR(_curses_unctrl__doc__,
"unctrl($module, ch, /)\n"
"--\n"
"\n"
-"Return a string which is a printable representation of the character ch.\n"
+"Return a bytes object which is a printable representation of ch.\n"
"\n"
-"Control characters are displayed as a caret followed by the character,\n"
-"for example as ^C. Printing characters are left as they are.");
+"Control characters are displayed as a caret followed by the\n"
+"character, for example as ^C. Printing characters are left as they\n"
+"are. Any attributes and color pair are ignored.");
#define _CURSES_UNCTRL_METHODDEF \
{"unctrl", (PyCFunction)_curses_unctrl, METH_O, _curses_unctrl__doc__},
@@ -4486,4 +4498,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=c1b7520d331d3d61 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=07421e6c7add461e 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]
