gh-151757: Support wide and combining characters in the curses module

The character-cell window methods now accept a full character cell -- a
spacing character optionally followed by combining characters (up to
CCHARW_MAX wide characters) -- in addition to a single int or byte
character.  This affects addch(), bkgd(), bkgdset(), border(), box(),
echochar(), hline(), insch() and vline(); they dispatch to the ncursesw
wide-character functions (wadd_wch(), wbkgrnd(), wborder_set(),
wecho_wchar(), whline_set(), wins_wch(), wvline_set(), ...) when given a
string.  border() and box() cannot mix integer or byte characters with
wide string characters in a single call.  A cell is one spacing character
optionally followed by combining characters, so an extra spacing or
control character (such as "ab") is rejected with ValueError rather than
being silently truncated by setcchar().

Also add the wide-character read methods get_wstr() and in_wstr(), the
counterparts of getstr() and instr() that return a str rather than a
bytes object, and the module functions erasewchar(), killwchar() and
wunctrl(), the wide-character counterparts of erasechar(), killchar()
and unctrl().

All of this is available only when built against the wide-character
ncursesw library.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: serhiy-storchaka

Doc/library/curses.rst

@@ -194,6 +194,16 @@ The module :mod:`!curses` defines the following functions:
    the curses library itself.
 
 
+.. function:: erasewchar()
+
+   Return the user's current erase character as a one-character string.
+   This is the wide-character variant of :func:`erasechar`.  Availability
+   depends on building Python against a wide-character-aware version of the
+   underlying curses library.
+
+   .. versionadded:: next
+
+
 .. function:: filter()
 
    The :func:`.filter` routine, if used, must be called before :func:`initscr` is
@@ -379,6 +389,16 @@ The module :mod:`!curses` defines the following functions:
    by the curses library itself.
 
 
+.. function:: killwchar()
+
+   Return the user's current line kill character as a one-character string.
+   This is the wide-character variant of :func:`killchar`.  Availability
+   depends on building Python against a wide-character-aware version of the
+   underlying curses library.
+
+   .. versionadded:: next
+
+
 .. function:: longname()
 
    Return a bytes object containing the terminfo long name field describing the current
@@ -690,6 +710,18 @@ The module :mod:`!curses` defines the following functions:
    example as ``b'^C'``. Printing characters are left as they are.
 
 
+.. function:: wunctrl(ch)
+
+   Return a string which is a printable representation of the wide character *ch*.
+   Control characters are represented as a caret followed by the character, for
+   example as ``'^C'``.  Printing characters are left as they are.  This is the
+   wide-character variant of :func:`unctrl`, returning a :class:`str` rather than
+   :class:`bytes`.  Availability depends on building Python against a
+   wide-character-aware version of the underlying curses library.
+
+   .. versionadded:: next
+
+
 .. function:: ungetch(ch)
 
    Push *ch* so the next :meth:`~window.getch` will return it.
@@ -770,12 +802,19 @@ Window objects
    character previously painted at that location.  By default, the character
    position and attributes are the current settings for the window object.
 
+   *ch* may be a single character, optionally followed by combining
+   characters, that together occupy one character cell.
+
    .. note::
 
       Writing outside the window, subwindow, or pad raises a :exc:`curses.error`.
       Attempting to write to the lower-right corner of a window, subwindow,
       or pad will cause an exception to be raised after the character is printed.
 
+   .. versionchanged:: next
+      A character may now be given as a string of a base character followed
+      by combining characters, instead of only a single character.
+
 
 .. method:: window.addnstr(str, n[, attr])
             window.addnstr(y, x, str, n[, attr])
@@ -834,6 +873,9 @@ Window objects
    * Wherever  the  former background character appears, it is changed to the new
      background character.
 
+   .. versionchanged:: next
+      Wide and combining characters are now accepted.
+
 
 .. method:: window.bkgdset(ch[, attr])
 
@@ -844,6 +886,9 @@ Window objects
    characters.  The background becomes a property of the character and moves with
    the character through any scrolling and insert/delete line/character operations.
 
+   .. versionchanged:: next
+      Wide and combining characters are now accepted.
+
 
 .. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])
 
@@ -877,12 +922,20 @@ Window objects
    | *br*      | Bottom-right corner | :const:`ACS_LRCORNER` |
    +-----------+---------------------+-----------------------+
 
+   .. versionchanged:: next
+      Wide and combining characters are now accepted.  A single call cannot mix
+      them with integer or byte characters.
+
 
 .. method:: window.box([vertch, horch])
 
    Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and
    *bs* are *horch*.  The default corner characters are always used by this function.
 
+   .. versionchanged:: next
+      Wide and combining characters are now accepted.  A single call cannot mix
+      them with integer or byte characters.
+
 
 .. method:: window.chgat(attr)
             window.chgat(num, attr)
@@ -951,6 +1004,9 @@ Window objects
    Add character *ch* with attribute *attr*, and immediately  call :meth:`refresh`
    on the window.
 
+   .. versionchanged:: next
+      Wide and combining characters are now accepted.
+
 
 .. method:: window.enclose(y, x)
 
@@ -1038,6 +1094,20 @@ Window objects
       The maximum value for *n* was increased from 1023 to 2047.
 
 
+.. method:: window.get_wstr()
+            window.get_wstr(n)
+            window.get_wstr(y, x)
+            window.get_wstr(y, x, n)
+
+   Read a string from the user, with primitive line editing capacity.
+   This is the wide-character variant of :meth:`getstr`: it returns a
+   :class:`str` rather than a :class:`bytes` object, so 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.
+
+   .. versionadded:: next
+
+
 .. method:: window.getyx()
 
    Return a tuple ``(y, x)`` of current cursor position  relative to the window's
@@ -1051,6 +1121,9 @@ Window objects
    the character *ch* with attributes *attr*.  The line stops at the right edge
    of the window if fewer than *n* cells are available.
 
+   .. versionchanged:: next
+      Wide and combining characters are now accepted.
+
 
 .. method:: window.idcok(flag)
 
@@ -1088,6 +1161,9 @@ Window objects
    cursor are shifted one position right, with the rightmost character on the
    line being lost.  The cursor position does not change.
 
+   .. versionchanged:: next
+      Wide and combining characters are now accepted.
+
 
 .. method:: window.insdelln(nlines)
 
@@ -1137,6 +1213,19 @@ Window objects
       The maximum value for *n* was increased from 1023 to 2047.
 
 
+.. 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.  This is the
+   wide-character variant of :meth:`instr`: it returns a :class:`str` rather
+   than a :class:`bytes` object, so 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.
+
+   .. versionadded:: next
+
+
 .. method:: window.is_linetouched(line)
 
    Return ``True`` if the specified line was modified since the last call to
@@ -1386,6 +1475,9 @@ Window objects
    Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
    character *ch* with attributes *attr*.
 
+   .. versionchanged:: next
+      Wide and combining characters are now accepted.
+
 
 Constants
 ---------

Doc/whatsnew/3.16.rst

@@ -89,6 +89,25 @@ Improved modules
 curses
 ------
 
+* The :mod:`curses` character-cell window methods now accept a full character
+  cell --- a spacing character optionally followed by combining characters ---
+  in addition to a single integer or byte character.  This affects
+  :meth:`~curses.window.addch`, :meth:`~curses.window.bkgd`,
+  :meth:`~curses.window.bkgdset`, :meth:`~curses.window.border`,
+  :meth:`~curses.window.box`, :meth:`~curses.window.echochar`,
+  :meth:`~curses.window.hline`, :meth:`~curses.window.insch` and
+  :meth:`~curses.window.vline`.
+  Also add the wide-character read methods :meth:`~curses.window.get_wstr` and
+  :meth:`~curses.window.in_wstr`, the counterparts of
+  :meth:`~curses.window.getstr` and :meth:`~curses.window.instr` that return a
+  :class:`str` rather than :class:`bytes`,
+  and the module functions :func:`curses.erasewchar`, :func:`curses.killwchar`
+  and :func:`curses.wunctrl`, the wide-character counterparts of
+  :func:`curses.erasechar`, :func:`curses.killchar` and :func:`curses.unctrl`.
+  These features are only available when built against the wide-character
+  ncursesw library.
+  (Contributed by Serhiy Storchaka in :gh:`151757`.)
+
 * Add :func:`curses.nofilter`, which undoes the effect of :func:`curses.filter`.
   (Contributed by Serhiy Storchaka in :gh:`151744`.)
 

Lib/test/test_curses.py

@@ -253,6 +253,69 @@ def test_refresh_control(self):
                 self.assertIs(win.is_wintouched(), syncok)
                 self.assertIs(stdscr.is_wintouched(), syncok)
 
+    @requires_curses_window_meth('get_wch')
+    def test_addch_combining(self):
+        # A character cell may hold a spacing char plus combining marks.
+        stdscr = self.stdscr
+        stdscr.move(0, 0)
+        stdscr.addch('e\u0301')              # 'e' + COMBINING ACUTE ACCENT
+        stdscr.addch(1, 0, 'a\u0323\u0300')  # base plus two combining marks
+        # Too many code points to fit in a single character cell.
+        self.assertRaises(TypeError, stdscr.addch, 'e' + '\u0301' * 10)
+        # Only the first code point may be a spacing character.
+        self.assertRaises(ValueError, stdscr.addch, 'ab')
+        self.assertRaises(ValueError, stdscr.addch, 'a\u0301b')
+        # A lone control character is allowed (like addch(ord('\n'))), but it
+        # cannot be combined with other characters, as base or otherwise.
+        stdscr.addch('\n')
+        self.assertRaises(ValueError, stdscr.addch, 'a\n')
+        self.assertRaises(ValueError, stdscr.addch, '\n\u0301')
+        self.assertRaises(ValueError, stdscr.addch, '\ne\u0301')
+
+    @requires_curses_window_meth('get_wch')
+    def test_addch_emoji(self):
+        # curses has no grapheme-cluster support: a cell holds one spacing
+        # character plus zero-width combining characters.  A lone emoji fits,
+        # as does an emoji with a zero-width variation selector.
+        stdscr = self.stdscr
+        stdscr.addch(0, 0, '\U0001f600')          # single emoji
+        stdscr.addch(1, 0, '\u263a\ufe0f')        # WHITE SMILING FACE + VS-16
+        # An emoji ZWJ sequence or an emoji with a modifier is more than one
+        # spacing character and cannot share a single cell.
+        self.assertRaises(ValueError, stdscr.addch,
+                          '\U0001f44d\U0001f3fd')          # thumbs up + skin tone
+        self.assertRaises(ValueError, stdscr.addch,
+                          '\U0001f468\u200d\U0001f469')    # man ZWJ woman
+
+    @requires_curses_window_meth('get_wch')
+    def test_wide_characters(self):
+        # Wide and combining characters in the character-cell methods.
+        stdscr = self.stdscr
+        combining = 'e\u0301'              # 'e' + COMBINING ACUTE ACCENT
+        vline, hline = '\u2502', '\u2500'  # box-drawing vertical/horizontal
+        stdscr.move(0, 0)
+        stdscr.echochar(combining)
+        stdscr.insch(1, 0, combining)
+        stdscr.hline(2, 0, hline, 5)
+        stdscr.vline(3, 0, vline, 3)
+        stdscr.bkgdset(combining)
+        stdscr.bkgd(combining)
+        stdscr.border(vline, vline, hline, hline)
+        stdscr.box(vline, hline)
+        # border() and box() cannot mix integer and wide-string characters.
+        self.assertRaises(TypeError, stdscr.box, vline, ord('-'))
+
+
+    @requires_curses_window_meth('in_wstr')
+    def test_in_wstr(self):
+        # The wide-character window read returns a str (instr returns bytes).
+        stdscr = self.stdscr
+        s = 'a\u00e9\u2502z'  # 'a', 'e'+acute (precomposed), box vline, 'z'
+        stdscr.addstr(0, 0, s)
+        self.assertEqual(stdscr.in_wstr(0, 0, len(s)), s)
+        self.assertIsInstance(stdscr.instr(0, 0, len(s)), bytes)
+
+
     def test_output_character(self):
         stdscr = self.stdscr
         encoding = stdscr.encoding
@@ -281,13 +344,16 @@ def test_output_character(self):
         stdscr.echochar('A')
         stdscr.echochar(b'A')
         stdscr.echochar(65)
-        with self.assertRaises((UnicodeEncodeError, OverflowError)):
-            # Unicode is not fully supported yet, but at least it does
-            # not crash.
-            # It is supposed to fail because either the character is
-            # not encodable with the current encoding, or it is encoded to
-            # a multibyte sequence.
-            stdscr.echochar('\u0114')
+        c = '\u0114'
+        try:
+            stdscr.echochar(c)
+        except UnicodeEncodeError:
+            # The character is not encodable with the current encoding.
+            self.assertRaises(UnicodeEncodeError, c.encode, encoding)
+        except OverflowError:
+            # The character is encoded to a multibyte sequence.
+            encoded = c.encode(encoding)
+            self.assertNotEqual(len(encoded), 1, repr(encoded))
         stdscr.echochar('A', curses.A_BOLD)
         self.assertIs(stdscr.is_wintouched(), False)
 
@@ -742,7 +808,6 @@ def test_borders_and_lines(self):
         self.assertEqual(win.inch(3, 1), b'a'[0])
 
     def test_unctrl(self):
-        # TODO: wunctrl()
         self.assertEqual(curses.unctrl(b'A'), b'A')
         self.assertEqual(curses.unctrl('A'), b'A')
         self.assertEqual(curses.unctrl(65), b'A')
@@ -753,6 +818,21 @@ def test_unctrl(self):
         self.assertRaises(TypeError, curses.unctrl, b'AB')
         self.assertRaises(TypeError, curses.unctrl, '')
         self.assertRaises(TypeError, curses.unctrl, 'AB')
+
+    @requires_curses_func('wunctrl')
+    def test_wunctrl(self):
+        # The wide-character variant of unctrl() returns a str.
+        self.assertEqual(curses.wunctrl(b'A'), 'A')
+        self.assertEqual(curses.wunctrl('A'), 'A')
+        self.assertEqual(curses.wunctrl(65), 'A')
+        self.assertEqual(curses.wunctrl('\n'), '^J')
+        self.assertEqual(curses.wunctrl(10), '^J')
+        self.assertEqual(curses.wunctrl('é'), 'é')  # printable
+        self.assertRaises(TypeError, curses.wunctrl, b'')
+        self.assertRaises(TypeError, curses.wunctrl, b'AB')
+        self.assertRaises(TypeError, curses.wunctrl, '')
+        # More than one spacing character is not a single cell.
+        self.assertRaises(ValueError, curses.wunctrl, 'AB')
         self.assertRaises(OverflowError, curses.unctrl, 2**64)
 
     def test_endwin(self):
@@ -800,7 +880,7 @@ def test_misc_module_funcs(self):
         curses.newpad(50, 50)
 
     def test_env_queries(self):
-        # TODO: term_attrs(), erasewchar(), killwchar()
+        # TODO: term_attrs()
         self.assertIsInstance(curses.termname(), bytes)
         self.assertIsInstance(curses.longname(), bytes)
         self.assertIsInstance(curses.baudrate(), int)
@@ -815,6 +895,24 @@ def test_env_queries(self):
         self.assertIsInstance(c, bytes)
         self.assertEqual(len(c), 1)
 
+        # The erase and kill characters are a property of the controlling
+        # terminal: the wide variants report ERR (raising curses.error) without
+        # one, while the narrow variants above return an unspecified byte.
+        try:
+            tty_fd = os.open(os.ctermid(), os.O_RDONLY)
+        except OSError:
+            tty_fd = None
+        if tty_fd is not None:
+            os.close(tty_fd)
+            if hasattr(curses, 'erasewchar'):
+                c = curses.erasewchar()
+                self.assertIsInstance(c, str)
+                self.assertEqual(len(c), 1)
+            if hasattr(curses, 'killwchar'):
+                c = curses.killwchar()
+                self.assertIsInstance(c, str)
+                self.assertEqual(len(c), 1)
+
     def test_output_options(self):
         stdscr = self.stdscr
 

Misc/NEWS.d/next/Library/2026-06-20-02-14-55.gh-issue-151757.TP9A2x.rst

@@ -0,0 +1,7 @@
+The :mod:`curses` character-cell window methods now accept a full character
+cell -- a spacing character optionally followed by combining characters -- in
+addition to a single integer or byte character.  Add the wide-character read
+methods :meth:`curses.window.get_wstr` and :meth:`curses.window.in_wstr`, and
+the functions :func:`curses.erasewchar`, :func:`curses.killwchar` and
+:func:`curses.wunctrl`.  These features are only available when built against
+the wide-character ncursesw library.