gh-83395: Add curses.window.in_wch

Doc/library/curses.rst

@@ -1017,6 +1017,18 @@ the following methods and attributes:
    Return the character at the given position in the window. The bottom 8 bits are
    the character proper, and upper bits are the attributes.
 
+   .. note::
+
+      ``inch`` only works for ASCII characters.  Use :meth:`in_wch` instead
+      for unicode support.
+
+.. method:: window.in_wch([x, y])
+
+   Return the wide character at the given position in the window.  The return
+   value is a 3-tuple ``(character, attributes, color_pair)``.
+
+   .. versionadded:: 3.14
+
 
 .. method:: window.insch(ch[, attr])
             window.insch(y, x, ch[, attr])

Lib/test/test_curses.py

@@ -1107,6 +1107,39 @@ def test_issue6243(self):
         curses.ungetch(1025)
         self.stdscr.getkey()
 
+    def test_in_wch(self):
+        stdscr = self.stdscr
+
+        if not hasattr(stdscr, 'in_wch'):
+            raise unittest.SkipTest('requires curses.window.in_wch')
+
+        if curses.has_colors():
+            curses.init_pair(1, curses.COLOR_RED, 0)
+            expected_pair = 1
+            color_attr = curses.color_pair(expected_pair)
+        else:
+            expected_pair = 0
+            color_attr = 0
+
+        def _norm(ch, attr, color):
+            # for some reason, curses returns some color bits here?
+            return ch, attr & ~curses.A_COLOR, color
+
+        for ch in ('a', '\xe9', '\u20ac', '\U0001f643'):
+            expected = (ch, curses.A_BOLD, expected_pair)
+
+            stdscr.insstr(0, 0, ch, color_attr | curses.A_BOLD)
+            self.assertEqual(_norm(*stdscr.in_wch()), expected)
+
+            stdscr.addstr(0, 0, ch, color_attr | curses.A_BOLD)
+            self.assertEqual(_norm(*stdscr.in_wch(0, 0)), expected)
+
+        # in_wch can return multiple characters in the case of zero width
+        # curses at max returns 5 characters in a cchar_t
+        stdscr.addstr(0, 0, 'a' + '\u200b' * 10)
+        expected = ('a\u200b\u200b\u200b\u200b', 0, 0)
+        self.assertEqual(stdscr.in_wch(0, 0), expected)
+
     @requires_curses_func('unget_wch')
     @unittest.skipIf(getattr(curses, 'ncurses_version', (99,)) < (5, 8),
                      "unget_wch is broken in ncurses 5.7 and earlier")

Misc/NEWS.d/next/Library/2020-01-04-15-46-15.bpo-39214.z0398o.rst

@@ -0,0 +1 @@
+Add :func:`curses.window.in_wch` function - by Anthony Sottile.

Modules/_cursesmodule.c

@@ -1736,6 +1736,54 @@ _curses_window_inch_impl(PyCursesWindowObject *self, int group_right_1,
     return rtn;
 }
 
+#ifdef HAVE_NCURSESW
+/*[clinic input]
+_curses.window.in_wch
+
+    [
+    y: int
+        Starting Y-coordinate.
+    x: int
+        Starting X-coordinate.
+    ]
+    /
+
+Retrieve the wide character at the gven position in the window.
+
+The return value is a 3-tuple of (character, attributes, color_pair).
+[clinic start generated code]*/
+
+static PyObject *
+_curses_window_in_wch_impl(PyCursesWindowObject *self, int group_right_1,
+                           int y, int x)
+/*[clinic end generated code: output=846ca8a82f2ecab4 input=5c20d96b592b0e0b]*/
+{
+    int ret;
+
+    cchar_t wcval;
+
+    wchar_t wstr[CCHARW_MAX + 1];
+    attr_t attr;
+    short color_pair;
+
+    if (group_right_1) {
+        ret = mvwin_wch(self->win, y, x, &wcval);
+    } else {
+        ret = win_wch(self->win, &wcval);
+    }
+    if (PyCursesCheckERR(ret, "in_wch") == NULL) {
+        return NULL;
+    }
+
+    ret = getcchar(&wcval, wstr, &attr, &color_pair, NULL);
+    if (PyCursesCheckERR(ret, "getcchar") == NULL) {
+        return NULL;
+    }
+
+    return Py_BuildValue("ukh", wstr, attr, color_pair);
+}
+#endif
+
 /*[-clinic input]
 _curses.window.instr
 
@@ -2530,6 +2578,7 @@ static PyMethodDef PyCursesWindow_Methods[] = {
     {"immedok",         (PyCFunction)PyCursesWindow_immedok, METH_VARARGS},
 #endif
     _CURSES_WINDOW_INCH_METHODDEF
+    _CURSES_WINDOW_IN_WCH_METHODDEF
     _CURSES_WINDOW_INSCH_METHODDEF
     {"insdelln",        (PyCFunction)PyCursesWindow_winsdelln, METH_VARARGS},
     {"insertln",        (PyCFunction)PyCursesWindow_winsertln, METH_NOARGS},