gh-156234: Fix and rewrite the curses documentation on reading (GH-156235)
serhiy-storchaka <[email protected]>
| Newsgroups | gmane.comp.python.cvs |
|---|---|
| Message-ID | <[email protected]> |
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]