https://github.com/python/cpython/commit/be87bfa8a1a68516cedc618c7cf5bb7b0b251678
commit: be87bfa8a1a68516cedc618c7cf5bb7b0b251678
branch: main
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2026-08-23T14:42:46+03:00
summary:
gh-156234: Fix and rewrite the curses documentation on reading (GH-156235)
Fix wrong types: instr() and getstr() return a bytes object, not a str, and
their n limits the number of bytes; getkey() returns a str; unctrl() returns
a bytes object. Make clear whether an integer standing for a character is an
encoded byte or a character code.
Rewrite the documentation of getch(), get_wch(), getkey(), getstr(),
get_wstr(), instr(), in_wstr() and in_wchstr(), following X/Open Curses.
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 c1afdb71c89e88..d6bccbb730f8b4 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -27,9 +27,15 @@ 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`.
+ Methods that write to a window accept also a character cell: a Unicode
+ string of a spacing character followed by combining characters, or a
+ :class:`complexchar`.
Whenever the documentation mentions a *character string* it can be specified
as a Unicode string or a byte string.
+ Methods that write to a window accept also a :class:`complexstr`.
.. note::
@@ -364,9 +370,9 @@ Keyboard input
Push *ch* so the next :meth:`~window.getch` or :meth:`~window.get_wch` will
return it.
- *ch* may be an integer (a key code or character code), a byte, or a string
of
- length 1. A one-character string is pushed like :func:`unget_wch`; on a
- narrow build it must encode to a single byte.
+ *ch* may be an integer (a key code or the code of an encoded byte), a byte,
+ or a string of length 1. A one-character string is pushed like
+ :func:`unget_wch`; on a narrow build it must encode to a single byte.
.. note::
@@ -380,6 +386,9 @@ Keyboard input
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.
@@ -1015,7 +1024,7 @@ Terminfo database
.. 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.
@@ -1024,8 +1033,8 @@ Terminfo database
.. 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.
@@ -1035,9 +1044,15 @@ Utilities
.. function:: unctrl(ch)
- Return a bytes object which is a printable representation of the character
*ch*.
- *ch* cannot be a character that does not fit in a single byte; use
- :func:`wunctrl` for those.
+ 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 a character,
+ for example as ``b'^C'``.
+ Printing characters are left as they are.
+ The representation of other characters is defined by the underlying curses
+ library.
+
+ *ch* must fit in a single byte; use :func:`wunctrl` for other characters.
.. function:: wunctrl(ch)
@@ -1264,19 +1279,47 @@ Reading input
.. 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.
- A multibyte character is returned as its encoded bytes one at a time; use
- :meth:`get_wch` to read it as a single character.
+ 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. Unlike :meth:`getch`,
an
- ordinary key is returned as a one-character :class:`str`.
- 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
@@ -1286,21 +1329,24 @@ Reading input
.. 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.getstr()
window.getstr(n)
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.
- A multibyte character is returned as its encoded bytes; use :meth:`get_wstr`
- to read the input as a :class:`str`.
+
+ Use :meth:`get_wstr` to read the input as a :class:`str`.
.. versionchanged:: 3.14
The maximum value for *n* was increased from 1023 to 2047.
@@ -1310,10 +1356,13 @@ Reading input
window.get_wstr(y, x)
window.get_wstr(y, x, n)
- Read a string from the user, with primitive line editing capacity.
- Unlike :meth:`getstr`, it can return characters that are not representable
in
- the window's encoding.
- At most *n* characters are read; *n* defaults to and cannot exceed 2047.
+ 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 :class:`str`, without the terminating newline.
+ At most *n* characters are read;
+ *n* defaults to and cannot exceed 2047.
+
+ This is the wide-character variant of :meth:`getstr`.
.. versionadded:: next
@@ -1354,13 +1403,13 @@ Reading window contents
.. 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.
- A character not representable in the window's encoding cannot be returned;
+ 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;
+ use :meth:`in_wchstr` to read them too.
+ At most *n* bytes are read; *n* defaults to and cannot exceed 2047.
+ A character not representable in the encoding cannot be returned;
use :meth:`in_wstr` for those.
.. versionchanged:: 3.14
@@ -1369,26 +1418,27 @@ Reading window contents
.. method:: window.in_wstr([n])
window.in_wstr(y, x[, n])
- Return a string of characters, extracted from the window starting at the
- current cursor position, or at *y*, *x* if specified. Unlike :meth:`instr`,
- it can return characters that are not representable in the window's
encoding.
- Attributes and color information are stripped from the characters. 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 :class:`str`.
+ Attributes and color pairs are stripped;
+ use :meth:`in_wchstr` to read them too.
+ At most *n* characters are read; *n* defaults to and cannot exceed 2047.
+
+ This is the wide-character variant of :meth:`instr`.
.. versionadded:: next
.. method:: window.in_wchstr([n])
window.in_wchstr(y, x[, n])
- Return a :class:`complexstr` of the styled cells extracted from the window
- starting at the current cursor position, or at *y*, *x* if specified, and
- stopping at the end of the line. This is the variant of :meth:`instr` and
- :meth:`in_wstr` that *keeps* each cell's attributes and color pair (those
- methods strip the rendition). If *n* is specified, at most *n* cells are
- returned. The maximum value for *n* is 2047.
-
- The result can be written back unchanged with :meth:`addstr` (a read and a
- re-write is a round-trip that preserves every cell's rendition).
+ Read the styled cells of the window from the current cursor position,
+ or from *y*, *x* if specified, to the end of the line,
+ and return them as a :class:`complexstr`.
+ Unlike :meth:`instr` and :meth:`in_wstr`, each cell keeps its attributes
+ and color pair, so the result can be written back unchanged
+ with :meth:`addstr`.
+ At most *n* cells are read; *n* defaults to and cannot exceed 2047.
.. versionadded:: next
@@ -1835,6 +1885,8 @@ Input options
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.nodelay(flag)
@@ -2331,6 +2383,8 @@ by some methods.
| .. data:: A_COLOR | | Bit-mask to extract
color-pair field information |
+-------------------------+--------------------------+--------------------------------------------------+
+.. _curses-key-constants:
+
Keys
~~~~
diff --git a/Modules/_cursesmodule.c b/Modules/_cursesmodule.c
index 7cc72b96d0a46d..82effccb1fe327 100644
--- a/Modules/_cursesmodule.c
+++ b/Modules/_cursesmodule.c
@@ -3342,18 +3342,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;
@@ -3394,18 +3401,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;
@@ -3453,16 +3460,20 @@ _curses.window.get_wch
]
/
-Get a wide character from terminal keyboard.
+Read a key press and return it as a one-character str.
-Return a character for most keys, or an integer for function keys,
-keypad keys, and other special keys.
+Wait until a key is pressed, or raise curses.error if the read is
+non-blocking or times out.
+
+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]*/
{
if (!curses_window_check_terminal(self)) {
return NULL;
@@ -3566,16 +3577,20 @@ _curses.window.getstr
X-coordinate.
]
n: unsigned_int = 2047
- Maximal number of characters.
+ Maximal number of bytes.
/
-Read a string from the user, with primitive line editing capacity.
+Read a line of input and return it as a bytes object.
+
+The input is read with primitive line editing capacity, encoded in
+the current locale, and does not include the terminating newline.
+At most n bytes are read.
[clinic start generated code]*/
static PyObject *
_curses_window_getstr_impl(PyCursesWindowObject *self, int group_left_1,
int y, int x, unsigned int n)
-/*[clinic end generated code: output=bea9b0ab7e8f34d9 input=c0fc273c2277a985]*/
+/*[clinic end generated code: output=bea9b0ab7e8f34d9 input=0335501e45f55caf]*/
{
if (!curses_window_check_terminal(self)) {
return NULL;
@@ -3842,23 +3857,21 @@ _curses.window.instr
X-coordinate.
]
n: unsigned_int = 2047
- Maximal number of characters.
+ Maximal number of bytes.
/
-Return a string of characters, extracted from the window.
+Return the text of the window as a bytes object.
-Return a string 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,
-instr() returns a string at most n characters long (exclusive of
-the trailing NUL).
+Read from the current cursor position, or from y, x if specified, to
+the end of the line, and return the text in the encoding of the
+current locale, with attributes and color pairs stripped. At most n
+bytes are read.
[clinic start generated code]*/
static PyObject *
_curses_window_instr_impl(PyCursesWindowObject *self, int group_left_1,
int y, int x, unsigned int n)
-/*[clinic end generated code: output=40081f67070132da input=85e62048d2d92642]*/
+/*[clinic end generated code: output=40081f67070132da input=4ece6af75b09346f]*/
{
return curses_window_instr_bytes(self, group_left_1, y, x, n);
}
@@ -3876,15 +3889,17 @@ _curses.window.get_wstr
Maximal number of characters.
/
-Read a string from the user, with primitive line editing capacity.
+Read a line of input and return it as a str.
-This is the wide-character variant of getstr(); it returns a str.
+This is the wide-character variant of getstr(). The input is read
+with primitive line editing capacity and does not include the
+terminating newline. At most n characters are read.
[clinic start generated code]*/
static PyObject *
_curses_window_get_wstr_impl(PyCursesWindowObject *self, int group_left_1,
int y, int x, unsigned int n)
-/*[clinic end generated code: output=e0a6670551cbe79f input=874fc230c4e82ca7]*/
+/*[clinic end generated code: output=e0a6670551cbe79f input=8920c99e9134670b]*/
{
if (!curses_window_check_terminal(self)) {
return NULL;
@@ -3960,15 +3975,18 @@ _curses.window.in_wstr
Maximal number of characters.
/
-Return a string of characters, extracted from the window.
+Return the text of the window as a str.
-This is the wide-character variant of instr(); it returns a str.
+This is the wide-character variant of instr(). Read from the
+current cursor position, or from y, x if specified, to the end of
+the line, with attributes and color pairs stripped. At most n
+characters are read.
[clinic start generated code]*/
static PyObject *
_curses_window_in_wstr_impl(PyCursesWindowObject *self, int group_left_1,
int y, int x, unsigned int n)
-/*[clinic end generated code: output=e3db72a1f10b9875 input=196703989dc57361]*/
+/*[clinic end generated code: output=e3db72a1f10b9875 input=436737264c54d8d3]*/
{
#ifdef HAVE_NCURSESW
int rtn;
@@ -4022,17 +4040,18 @@ _curses.window.in_wchstr
Maximal number of cells.
/
-Return a complexstr of the styled cells extracted from the window.
+Return the styled cells of the window as a complexstr.
-This is the wide-character variant of instr() and in_wstr() that
-keeps each cell's attributes and color pair; it returns a
-complexstr.
+Read from the current cursor position, or from y, x if specified, to
+the end of the line. Unlike instr() and in_wstr(), each cell keeps
+its attributes and color pair, so the result can be written back
+unchanged with addstr(). At most n cells are read.
[clinic start generated code]*/
static PyObject *
_curses_window_in_wchstr_impl(PyCursesWindowObject *self, int group_left_1,
int y, int x, unsigned int n)
-/*[clinic end generated code: output=7fb5216f2088835b input=b725c0b8abff62c2]*/
+/*[clinic end generated code: output=7fb5216f2088835b input=8104e661c3cb7fea]*/
{
int rtn;
unsigned int max_buf_size = 2048;
@@ -8270,15 +8289,17 @@ _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. ch must fit in a
+single byte; use wunctrl() for other characters.
[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=eed6686669f5ca21]*/
{
chtype ch_;
diff --git a/Modules/clinic/_cursesmodule.c.h b/Modules/clinic/_cursesmodule.c.h
index d2f30178b1c33c..61c324e04c5bdc 100644
--- a/Modules/clinic/_cursesmodule.c.h
+++ b/Modules/clinic/_cursesmodule.c.h
@@ -1328,17 +1328,24 @@ _curses_window_getbkgrnd(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__},
@@ -1376,17 +1383,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__},
@@ -1424,15 +1431,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__},
@@ -1470,14 +1481,18 @@ _curses_window_get_wch(PyObject *self, 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.\n"
+"\n"
+"The input is read with primitive line editing capacity, encoded in\n"
+"the current locale, and does not include the terminating newline.\n"
+"At most n bytes are read.");
#define _CURSES_WINDOW_GETSTR_METHODDEF \
{"getstr", (PyCFunction)_curses_window_getstr, METH_VARARGS,
_curses_window_getstr__doc__},
@@ -1707,21 +1722,19 @@ _curses_window_inch(PyObject *self, PyObject *args)
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.");
#define _CURSES_WINDOW_INSTR_METHODDEF \
{"instr", (PyCFunction)_curses_window_instr, METH_VARARGS,
_curses_window_instr__doc__},
@@ -1765,7 +1778,7 @@ _curses_window_instr(PyObject *self, PyObject *args)
PyDoc_STRVAR(_curses_window_get_wstr__doc__,
"get_wstr([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 str.\n"
"\n"
" y\n"
" Y-coordinate.\n"
@@ -1774,7 +1787,9 @@ PyDoc_STRVAR(_curses_window_get_wstr__doc__,
" n\n"
" Maximal number of characters.\n"
"\n"
-"This is the wide-character variant of getstr(); it returns a str.");
+"This is the wide-character variant of getstr(). The input is read\n"
+"with primitive line editing capacity and does not include the\n"
+"terminating newline. At most n characters are read.");
#define _CURSES_WINDOW_GET_WSTR_METHODDEF \
{"get_wstr", (PyCFunction)_curses_window_get_wstr, METH_VARARGS,
_curses_window_get_wstr__doc__},
@@ -1818,7 +1833,7 @@ _curses_window_get_wstr(PyObject *self, PyObject *args)
PyDoc_STRVAR(_curses_window_in_wstr__doc__,
"in_wstr([y, x,] n=2047)\n"
-"Return a string of characters, extracted from the window.\n"
+"Return the text of the window as a str.\n"
"\n"
" y\n"
" Y-coordinate.\n"
@@ -1827,7 +1842,10 @@ PyDoc_STRVAR(_curses_window_in_wstr__doc__,
" n\n"
" Maximal number of characters.\n"
"\n"
-"This is the wide-character variant of instr(); it returns a str.");
+"This is the wide-character variant of instr(). Read from the\n"
+"current cursor position, or from y, x if specified, to the end of\n"
+"the line, with attributes and color pairs stripped. At most n\n"
+"characters are read.");
#define _CURSES_WINDOW_IN_WSTR_METHODDEF \
{"in_wstr", (PyCFunction)_curses_window_in_wstr, METH_VARARGS,
_curses_window_in_wstr__doc__},
@@ -1871,7 +1889,7 @@ _curses_window_in_wstr(PyObject *self, PyObject *args)
PyDoc_STRVAR(_curses_window_in_wchstr__doc__,
"in_wchstr([y, x,] n=2047)\n"
-"Return a complexstr of the styled cells extracted from the window.\n"
+"Return the styled cells of the window as a complexstr.\n"
"\n"
" y\n"
" Y-coordinate.\n"
@@ -1880,9 +1898,10 @@ PyDoc_STRVAR(_curses_window_in_wchstr__doc__,
" n\n"
" Maximal number of cells.\n"
"\n"
-"This is the wide-character variant of instr() and in_wstr() that\n"
-"keeps each cell\'s attributes and color pair; it returns a\n"
-"complexstr.");
+"Read from the current cursor position, or from y, x if specified, to\n"
+"the end of the line. Unlike instr() and in_wstr(), each cell keeps\n"
+"its attributes and color pair, so the result can be written back\n"
+"unchanged with addstr(). At most n cells are read.");
#define _CURSES_WINDOW_IN_WCHSTR_METHODDEF \
{"in_wchstr", (PyCFunction)_curses_window_in_wchstr, METH_VARARGS,
_curses_window_in_wchstr__doc__},
@@ -5754,10 +5773,12 @@ 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. ch must fit in a\n"
+"single byte; use wunctrl() for other characters.");
#define _CURSES_UNCTRL_METHODDEF \
{"unctrl", (PyCFunction)_curses_unctrl, METH_O, _curses_unctrl__doc__},
@@ -6582,4 +6603,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=4e98ddbfb69f2c04 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=5616d0371c2240be 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]
