From 7e1ab2f517a2481e58f0bb0b383c121fbab77aee Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Tue, 8 Sep 2026 01:52:18 +0300 Subject: [PATCH 1/3] gh-157140: Correct five curses documentation statements halfdelay() does not raise on timeout, getch() returns -1; termname() is not truncated to 14 characters; scroll() raises curses.error rather than doing nothing without scrollok(); insnstr() inserts nothing for n == 0, not the whole string; and insch(y, x, ch) moves the cursor. --- Doc/library/curses.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index bcf2ef47d48898a..f191678dd125cc1 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -274,9 +274,9 @@ Input options Used for half-delay mode, which is similar to cbreak mode in that characters typed by the user are immediately available to the program. However, after - blocking for *tenths* tenths of seconds, raise an exception if nothing has - been typed. The value of *tenths* must be a number between ``1`` and ``255``. Use - :func:`nocbreak` to leave half-delay mode. + blocking for *tenths* tenths of seconds, :meth:`~window.getch` returns ``-1`` + if nothing has been typed. The value of *tenths* must be a number between + ``1`` and ``255``. Use :func:`nocbreak` to leave half-delay mode. .. function:: meta(flag) @@ -891,8 +891,8 @@ Querying the terminal .. function:: termname() - Return the value of the environment variable :envvar:`TERM`, as a bytes object, - truncated to 14 characters. + Return the value of the environment variable :envvar:`TERM`, as a bytes + object. .. function:: longname() @@ -1215,7 +1215,8 @@ Adding and inserting text Insert character *ch* with attributes *attr* before the character under the cursor, or at ``(y, x)`` if specified. All characters to the right of the cursor are shifted one position right, with the rightmost character on the - line being lost. The cursor position does not change. + line being lost. The cursor position does not change (after moving to *y*, + *x*, if specified). .. versionchanged:: next Wide and combining characters, and :class:`complexchar` cells, are now @@ -1239,9 +1240,9 @@ Adding and inserting text window.insnstr(y, x, str, n[, attr]) Insert a character string (as many characters as will fit on the line) before - the character under the cursor, up to *n* characters. If *n* is zero or - negative, the entire string is inserted. All characters to the right of the - cursor are shifted right, with the rightmost characters on the line being lost. + the character under the cursor, up to *n* characters. If *n* is negative, + the entire string is inserted. All characters to the right of the cursor are + shifted right, with the rightmost characters on the line being lost. The cursor position does not change (after moving to *y*, *x*, if specified). .. versionchanged:: next @@ -1859,8 +1860,9 @@ Output options .. method:: window.scroll([lines=1]) Scroll the screen or scrolling region. Scroll upward by *lines* lines if - *lines* is positive, or downward if it is negative. Scrolling has no effect - unless it has been enabled for the window with :meth:`scrollok`. + *lines* is positive, or downward if it is negative. Raise + :exc:`curses.error` unless scrolling has been enabled for the window with + :meth:`scrollok`. .. method:: window.setscrreg(top, bottom) From a7ccf0ac787700d2f4fac01182939cee4add40b5 Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Wed, 9 Sep 2026 13:21:41 +0300 Subject: [PATCH 2/3] Address review comments halfdelay() now says that getkey() and get_wch() raise while getch() returns -1; termname() describes the name of the terminal in use rather than TERM alone, and keeps the 14-character note as a library-dependent caveat; the touched paragraphs use semantic line breaks so that no line is reflowed needlessly. --- Doc/library/curses.rst | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index f191678dd125cc1..99831bb001e3722 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -274,9 +274,11 @@ Input options Used for half-delay mode, which is similar to cbreak mode in that characters typed by the user are immediately available to the program. However, after - blocking for *tenths* tenths of seconds, :meth:`~window.getch` returns ``-1`` - if nothing has been typed. The value of *tenths* must be a number between - ``1`` and ``255``. Use :func:`nocbreak` to leave half-delay mode. + blocking for *tenths* tenths of seconds, if nothing has been typed, + :meth:`~window.getch` returns ``-1``, while :meth:`~window.getkey` and + :meth:`~window.get_wch` raise :exc:`curses.error`. + The value of *tenths* must be a number between ``1`` and ``255``. + Use :func:`nocbreak` to leave half-delay mode. .. function:: meta(flag) @@ -891,8 +893,10 @@ Querying the terminal .. function:: termname() - Return the value of the environment variable :envvar:`TERM`, as a bytes - object. + Return the name of the terminal in use, as a bytes object. + This is the name passed to :func:`initscr`, :func:`newterm` or + :func:`setupterm`, or the value of the :envvar:`TERM` environment variable + if none was given. Some curses libraries truncate it to 14 characters. .. function:: longname() @@ -1215,8 +1219,8 @@ Adding and inserting text Insert character *ch* with attributes *attr* before the character under the cursor, or at ``(y, x)`` if specified. All characters to the right of the cursor are shifted one position right, with the rightmost character on the - line being lost. The cursor position does not change (after moving to *y*, - *x*, if specified). + line being lost. + The cursor position does not change (after moving to *y*, *x*, if specified). .. versionchanged:: next Wide and combining characters, and :class:`complexchar` cells, are now @@ -1241,8 +1245,8 @@ Adding and inserting text Insert a character string (as many characters as will fit on the line) before the character under the cursor, up to *n* characters. If *n* is negative, - the entire string is inserted. All characters to the right of the cursor are - shifted right, with the rightmost characters on the line being lost. + the entire string is inserted. All characters to the right of the + cursor are shifted right, with the rightmost characters on the line being lost. The cursor position does not change (after moving to *y*, *x*, if specified). .. versionchanged:: next @@ -1860,9 +1864,9 @@ Output options .. method:: window.scroll([lines=1]) Scroll the screen or scrolling region. Scroll upward by *lines* lines if - *lines* is positive, or downward if it is negative. Raise - :exc:`curses.error` unless scrolling has been enabled for the window with - :meth:`scrollok`. + *lines* is positive, or downward if it is negative. + Raise :exc:`curses.error` unless scrolling has been enabled for the window + with :meth:`scrollok`. .. method:: window.setscrreg(top, bottom) From b3b157985a3f5c16eb09d04561e93668ec73c7ed Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Sun, 13 Sep 2026 23:00:48 -0400 Subject: [PATCH 3/3] Drop initscr() from termname(), it takes no terminal name --- Doc/library/curses.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 99831bb001e3722..f879bccddf79abe 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -894,7 +894,7 @@ Querying the terminal .. function:: termname() Return the name of the terminal in use, as a bytes object. - This is the name passed to :func:`initscr`, :func:`newterm` or + This is the name passed to :func:`newterm` or :func:`setupterm`, or the value of the :envvar:`TERM` environment variable if none was given. Some curses libraries truncate it to 14 characters.