gh-90092: Support multiple terminals in the curses module

Add the X/Open Curses SCREEN API for driving more than one terminal:
newterm() and set_term(), plus the ncurses extension new_prescr().

A new screen object wraps the C SCREEN.  It exposes the terminal's
standard window as screen.stdscr.  Each window keeps a reference to its
screen (like a subwindow does to its parent window), so the screen is
deleted automatically once it and all of its windows are unreferenced.

The ncurses use_screen()/use_window() locking helpers are exposed as
the screen.use() and window.use() methods.

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

Author: serhiy-storchaka

Doc/library/curses.rst

@@ -207,8 +207,9 @@ The module :mod:`!curses` defines the following functions:
 .. function:: nofilter()
 
    Undo the effect of a previous :func:`.filter` call.
-   Like :func:`.filter`, it must be called before :func:`initscr` so that the
-   next initialization uses the full screen again.
+   Like :func:`.filter`, it must be called before :func:`initscr` (or
+   :func:`newterm`) so that the next initialization uses the full screen
+   again.
 
    Availability: if the underlying curses library provides ``nofilter()``.
 
@@ -442,6 +443,36 @@ The module :mod:`!curses` defines the following functions:
    right corner of the screen.
 
 
+.. function:: newterm(type=None, fd=None, infd=None, /)
+
+   Initialize a new terminal in addition to the one initialized by
+   :func:`initscr`,
+   and return a :ref:`screen <curses-screen-objects>` for it.
+   This allows a program to drive more than one terminal.
+
+   *type* is the terminal name, as in :func:`setupterm`;
+   if ``None``, the value of the :envvar:`TERM` environment variable is used.
+   *fd* and *infd* are the output and input files for the terminal:
+   either a file object or a file descriptor.
+   They default to :data:`sys.stdout` and :data:`sys.stdin`.
+
+   The new screen becomes the current one.
+   Use :func:`set_term` to switch between screens.
+
+   .. versionadded:: next
+
+
+.. function:: new_prescr()
+
+   Return a new :ref:`screen <curses-screen-objects>`
+   that can be used to call functions that affect global state
+   before :func:`initscr` or :func:`newterm` is called.
+
+   Availability: if the underlying curses library provides ``new_prescr()``.
+
+   .. versionadded:: next
+
+
 .. function:: nl(flag=True)
 
    Enter newline mode.  This mode translates the return key into newline on input,
@@ -586,6 +617,17 @@ The module :mod:`!curses` defines the following functions:
 
    .. versionadded:: 3.9
 
+
+.. function:: set_term(screen, /)
+
+   Make *screen*, a :ref:`screen <curses-screen-objects>` returned by
+   :func:`newterm`, the current terminal,
+   and return the previously current screen.
+   Returns ``None`` if the previous screen was the one created by
+   :func:`initscr`.
+
+   .. versionadded:: next
+
 .. function:: setsyx(y, x)
 
    Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, then
@@ -1380,13 +1422,65 @@ Window objects
    :meth:`refresh`.
 
 
+.. method:: window.use(func, /, *args, **kwargs)
+
+   Call ``func(window, *args, **kwargs)`` with the lock of the window held,
+   and return its result.
+   This provides automatic protection for the window
+   against concurrent access from another thread.
+
+   Availability: if the underlying curses library provides ``use_window()``.
+
+   .. versionadded:: next
+
+
 .. method:: window.vline(ch, n[, attr])
             window.vline(y, x, ch, n[, attr])
 
    Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
    character *ch* with attributes *attr*.
 
 
+.. _curses-screen-objects:
+
+Screen objects
+--------------
+
+.. class:: screen
+
+   A *screen* object represents a terminal initialized by :func:`newterm`
+   (or :func:`new_prescr`),
+   in addition to the default screen created by :func:`initscr`.
+   Screen objects are returned by those functions;
+   they cannot be instantiated directly.
+
+   A screen is freed automatically once it is no longer referenced,
+   either directly or through one of its windows.
+   Each window keeps its screen alive,
+   so a screen remains valid as long as any of its windows does.
+
+   .. versionadded:: next
+
+
+.. attribute:: screen.stdscr
+
+   The standard :ref:`window <curses-window-objects>` of the screen,
+   covering the whole terminal,
+   or ``None`` for a screen created by :func:`new_prescr`.
+
+
+.. method:: screen.use(func, /, *args, **kwargs)
+
+   Call ``func(screen, *args, **kwargs)`` with the lock of the screen held,
+   and return its result.
+   This provides automatic protection for the screen
+   against concurrent access from another thread.
+
+   Availability: if the underlying curses library provides ``use_screen()``.
+
+   .. versionadded:: next
+
+
 Constants
 ---------
 

Doc/whatsnew/3.16.rst

@@ -89,6 +89,13 @@ Improved modules
 curses
 ------
 
+* Add support for multiple terminals to the :mod:`curses` module:
+  the new functions :func:`curses.newterm`, :func:`curses.set_term`
+  and :func:`curses.new_prescr`,
+  the corresponding :ref:`screen <curses-screen-objects>` object,
+  and the :meth:`window.use` method.
+  (Contributed by Serhiy Storchaka in :gh:`90092`.)
+
 * Add :func:`curses.nofilter`, which undoes the effect of :func:`curses.filter`.
   (Contributed by Serhiy Storchaka in :gh:`151744`.)
 

Include/py_curses.h

@@ -80,8 +80,18 @@ typedef struct PyCursesWindowObject {
     WINDOW *win;
     char *encoding;
     struct PyCursesWindowObject *orig;
+    PyObject *screen;        /* the screen the window belongs to, or NULL,
+                                kept alive for the lifetime of the window */
 } PyCursesWindowObject;
 
+typedef struct {
+    PyObject_HEAD
+    SCREEN *screen;          /* NULL after the screen has been deleted */
+    FILE *outfp;             /* owned output stream, or NULL */
+    FILE *infp;              /* owned input stream, or NULL */
+    PyObject *stdscr;        /* the screen's standard window, or NULL */
+} PyCursesScreenObject;
+
 #define PyCurses_CAPSULE_NAME "_curses._C_API"
 
 

Lib/curses/__init__.py

@@ -34,6 +34,23 @@ def initscr():
             setattr(curses, key, value)
     return stdscr
 
+# newterm() is wrapped for the same reason as initscr(): the ACS_* constants
+# and LINES/COLS only become available once a terminal is initialized, and are
+# then copied to the curses package's dictionary.
+
+try:
+    newterm
+except NameError:
+    pass
+else:
+    def newterm(type=None, fd=None, infd=None, /):
+        import _curses, curses
+        screen = _curses.newterm(type, fd, infd)
+        for key, value in _curses.__dict__.items():
+            if key.startswith('ACS_') or key in ('LINES', 'COLS'):
+                setattr(curses, key, value)
+        return screen
+
 # This is a similar wrapper for start_color(), which adds the COLORS and
 # COLOR_PAIRS variables which are only available after start_color() is
 # called.

Lib/test/test_curses.py

@@ -53,9 +53,11 @@ def wrapped(self, *args, **kwargs):
 term = os.environ.get('TERM')
 SHORT_MAX = 0x7fff
 
-# If newterm was supported we could use it instead of initscr and not exit
+# newterm() is used when available (it reports errors instead of exiting), but
+# initscr() is still the fallback, and an unusable $TERM has no terminal to
+# drive either way.
 @unittest.skipIf(not term or term == 'unknown',
-                 "$TERM=%r, calling initscr() may cause exit" % term)
+                 "$TERM=%r, no usable terminal" % term)
 @unittest.skipIf(sys.platform == "cygwin",
                  "cygwin's curses mostly just hangs")
 class TestCurses(unittest.TestCase):
@@ -110,7 +112,23 @@ def setUp(self):
             sys.stderr.flush()
             sys.stdout.flush()
             print(file=self.output, flush=True)
-        self.stdscr = curses.initscr()
+        if hasattr(curses, 'newterm'):
+            # Use newterm() rather than initscr(): it reports errors instead of
+            # exiting, and gives each test a fresh screen, which also lets
+            # ScreenTests run newterm()/set_term() in the same process.
+            try:
+                infd = sys.__stdin__.fileno()
+            except (AttributeError, ValueError, OSError):
+                infd = stdout_fd
+            self.screen = curses.newterm(term, stdout_fd, infd)
+            self.stdscr = self.screen.stdscr
+            # Drop the screen after the test so the screens do not pile up: a
+            # window keeps its screen alive through a reference cycle, and
+            # unittest keeps every test instance for the whole run.
+            self.addCleanup(setattr, self, 'screen', None)
+            self.addCleanup(setattr, self, 'stdscr', None)
+        else:
+            self.stdscr = curses.initscr()
         if self.isatty:
             curses.savetty()
             self.addCleanup(curses.endwin)
@@ -119,10 +137,12 @@ def setUp(self):
 
     @requires_curses_func('filter')
     def test_filter(self):
-        # TODO: Should be called before initscr() or newterm() are called.
+        # filter() must be called before initscr()/newterm(); it confines
+        # curses to a single line.  Undo it with nofilter() afterwards so that
+        # it does not shrink the screens created by later tests.
         curses.filter()
         if hasattr(curses, 'nofilter'):
-            curses.nofilter()
+            self.addCleanup(curses.nofilter)
 
     @requires_curses_func('use_env')
     def test_use_env(self):
@@ -1089,6 +1109,22 @@ def test_use_default_colors(self):
             self.skipTest('cannot change color (use_default_colors() failed)')
         self.assertEqual(curses.pair_content(0), (-1, -1))
 
+    @requires_curses_window_meth('use')
+    def test_use_window(self):
+        win = self.stdscr
+        self.assertEqual(win.use(lambda w, a, b: (w is win, a, b), 5, b=6),
+                         (True, 5, 6))
+        with self.assertRaises(ZeroDivisionError):
+            win.use(lambda w: 1 / 0)
+
+    @unittest.skipUnless(hasattr(curses.screen, 'use'),
+                         'requires screen.use()')
+    def test_use_screen(self):
+        screen = self.screen
+        self.assertEqual(
+            screen.use(lambda sc, flag: (sc is screen, flag), flag=True),
+            (True, True))
+
     @requires_curses_func('assume_default_colors')
     @requires_colors
     def test_assume_default_colors(self):
@@ -1387,9 +1423,11 @@ def test_resize_term(self):
             curses.resize_term(35000, 1)
         with self.assertRaises(OverflowError):
             curses.resize_term(1, 35000)
-        # GH-120378: Overflow failure in resize_term() causes refresh to fail
-        tmp = curses.initscr()
-        tmp.erase()
+        # GH-120378: a failed resize can leave refresh broken; restore the
+        # original size to recover.  Avoid initscr(), which would switch away
+        # from the shared newterm() screen and corrupt later tests.
+        curses.resize_term(lines, cols)
+        self.stdscr.erase()
 
     @requires_curses_func('resizeterm')
     def test_resizeterm(self):
@@ -1409,9 +1447,11 @@ def test_resizeterm(self):
             curses.resizeterm(35000, 1)
         with self.assertRaises(OverflowError):
             curses.resizeterm(1, 35000)
-        # GH-120378: Overflow failure in resizeterm() causes refresh to fail
-        tmp = curses.initscr()
-        tmp.erase()
+        # GH-120378: a failed resize can leave refresh broken; restore the
+        # original size to recover.  Avoid initscr(), which would switch away
+        # from the shared newterm() screen and corrupt later tests.
+        curses.resizeterm(lines, cols)
+        self.stdscr.erase()
 
     def test_ungetch(self):
         curses.ungetch(b'A')
@@ -1717,5 +1757,98 @@ def test_move_down(self):
         self.mock_win.reset_mock()
 
 
+@unittest.skipUnless(hasattr(curses, 'newterm'), 'requires curses.newterm()')
+@unittest.skipIf(not term or term == 'unknown',
+                 "$TERM=%r, newterm() may not work" % term)
+@unittest.skipIf(sys.platform == "cygwin",
+                 "cygwin's curses mostly just hangs")
+class ScreenTests(unittest.TestCase):
+    # newterm()/set_term() mutate global curses state, but each test drives its
+    # own pseudo-terminal(s) and never touches the screen shared by TestCurses,
+    # whose setUp() makes that screen current again.  So these can run in this
+    # process, without a real terminal and without a subprocess.
+
+    def setUp(self):
+        # newterm() may install signal handlers; restore them afterwards.
+        self.save_signals = SaveSignals()
+        self.save_signals.save()
+        self.addCleanup(self.save_signals.restore)
+
+    def tearDown(self):
+        # Leave visual mode and reclaim the screens the test created, while
+        # their pseudo-terminals are still open (closing them happens later,
+        # via the make_pty() cleanups).
+        try:
+            curses.endwin()
+        except curses.error:
+            pass
+        gc_collect()
+
+    def make_pty(self):
+        master, slave = os.openpty()
+        self.addCleanup(os.close, master)
+        self.addCleanup(os.close, slave)
+        return slave
+
+    def test_newterm(self):
+        s = self.make_pty()
+        screen = curses.newterm('xterm', s, s)
+        self.assertIsInstance(screen, curses.screen)
+        win = screen.stdscr
+        self.assertIsInstance(win, curses.window)
+        self.assertEqual(win.getmaxyx(), (24, 80))
+        win.addstr(0, 0, 'hello')
+        win.refresh()
+
+    def test_newterm_file_object(self):
+        # type=None uses $TERM; the file arguments accept file objects too.
+        s = self.make_pty()
+        out = os.fdopen(os.dup(s), 'wb', buffering=0)
+        self.addCleanup(out.close)
+        screen = curses.newterm(None, out, s)
+        self.assertIsInstance(screen, curses.screen)
+
+    def test_set_term(self):
+        s = self.make_pty()
+        s2 = self.make_pty()
+        a = curses.newterm('xterm', s, s)     # current screen is a
+        b = curses.newterm('xterm', s2, s2)   # current screen is b
+        self.assertIs(curses.set_term(a), b)  # returns the previous one
+        self.assertIs(curses.set_term(b), a)
+
+    def test_window_keeps_screen_alive(self):
+        # The standard window keeps its screen alive; dropping every other
+        # reference and collecting must not invalidate the window.
+        s = self.make_pty()
+        win = curses.newterm('xterm', s, s).stdscr
+        gc_collect()
+        win.addstr(0, 0, 'still alive')
+        win.refresh()
+
+    def test_screen_freed(self):
+        # Dropping all references to a (non-current) screen and its windows
+        # frees it without error.
+        s = self.make_pty()
+        s2 = self.make_pty()
+        a = curses.newterm('xterm', s, s)
+        b = curses.newterm('xterm', s2, s2)   # a is no longer current
+        del a
+        gc_collect()
+
+    @unittest.skipUnless(hasattr(curses, 'new_prescr'),
+                         'requires curses.new_prescr()')
+    def test_new_prescr(self):
+        screen = curses.new_prescr()
+        self.assertIsInstance(screen, curses.screen)
+        self.assertIsNone(screen.stdscr)
+        del screen
+        gc_collect()
+
+    @cpython_only
+    def test_disallow_instantiation(self):
+        # The screen type cannot be instantiated directly (bpo-43916).
+        check_disallow_instantiation(self, curses.screen)
+
+
 if __name__ == '__main__':
     unittest.main()