gh-90092: Support multiple terminals in the curses module (GH-151748)

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

@@ -217,8 +217,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()``.
 
@@ -462,6 +463,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,
@@ -606,6 +637,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
@@ -1469,6 +1511,18 @@ 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])
 
@@ -1479,6 +1533,60 @@ Window objects
       Wide and combining characters are now accepted.
 
 
+.. _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
+
+
+.. method:: screen.close()
+
+   Detach the screen's standard window,
+   breaking the reference cycle between them
+   so the screen can be reclaimed promptly instead of waiting for a
+   garbage collection.
+   Afterwards :attr:`~screen.stdscr` is ``None``
+   and the window it returned earlier can no longer be used.
+   The screen's resources are released
+   once it and all its windows are no longer referenced.
+
+   .. 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() <curses.window.use>` method.
+  (Contributed by Serhiy Storchaka in :gh:`90092`.)
+
 * 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

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.