gh-90092: Support multiple terminals in the curses module by serhiy-storchaka · Pull Request #151748 · python/cpython · GitHub

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

A new screen object wraps the C SCREEN and 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 a screen is freed automatically once it and all of its windows are unreferenced. delscreen() is deferred to the screen object's deallocation rather than its tp_clear, so it runs only after the screen's windows — and any panels built on them — are gone.

The ncurses use_screen()/use_window() locking helpers are exposed as the screen.use() and window.use() methods, forwarding *args and **kwargs to the callable.

ScreenTests now run in-process over pseudo-terminals instead of subprocesses, and TestCurses drives a newterm() screen, so the new API is exercised without needing a second real terminal.

🤖 Generated with Claude Code

Issue: python curses newterm implementation #90092

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>

Documentation build overview

📚 cpython-previews | 🛠️ Build #33288117 | 📁 Comparing 86d808e against main (2e5843e)

🔍 Preview build

17 files changed · ± 17 modified

± Modified

Should we not be using the directive?

No, it only supports limited set of OS names.

Doc failures require merging #151643 first.

ScreenTests drives curses over pseudo-terminals whose master ends are never read. On macOS (unlike Linux) the tcdrain() that curses performs inside endwin(), and even a plain write(), blocks once the unread output fills the pty buffer, so the test hung until the timeout. Drain the masters synchronously before endwin(), leaving room for its output. Also release the GIL around the endwin() call, so that it no longer blocks other threads while it talks to the terminal. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The synchronous drain before endwin() is not enough on macOS: endwin()'s own output can again exceed the pty buffer, so its tcdrain() blocks even after the buffer was emptied. Drain each master continuously from a background thread instead; the endwin() GIL release lets that thread run while endwin() blocks. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

On macOS, closing the pty slave while the master is still open blocks until the slave's pending output drains. Closing the master first stops the reader thread and leaves nothing for the slave close to wait for. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

On macOS, closing either end of a pty while a thread is blocked in read() on the master hangs. Drain with a poll() loop that a stop Event can interrupt, and stop and join the reader before closing the descriptors. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Each test's newterm() screen forms a window<->screen reference cycle, reclaimed only by the cyclic GC. Collect it while the screen is still current, so the windows' delwin() succeeds; collected later, on a non-current screen, it fails (an unraisable error that trips --fail-env-changed on macOS). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

A screen and its standard window reference each other, so a screen is only reclaimed by the cyclic garbage collector. screen.close() detaches the standard window -- clearing the cycle and the window so its delwin() is skipped (delscreen() frees it instead) -- letting the screen be released by reference counting. Afterwards screen.stdscr is None and the old window raises curses.error. Use it in the tests instead of an explicit gc.collect(). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Unlike the sibling panel tests, test_userptr_segfault never removed its panel, so the window it wrapped was reachable only through a panel<->userptr __del__ cycle and was collected during a much later test, where delwin() failed on macOS (--fail-env-changed). Give it the addCleanup(self._delete_panels, ...) the other panel tests use; the per-test screen.close() in setUp then keeps the teardown free of lingering cycles. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

# Conflicts: # Doc/whatsnew/3.16.rst # Modules/clinic/_cursesmodule.c.h

The bare window.use reference could not resolve in whatsnew (no currentmodule), causing a docs CI warning; qualify it to curses.window.use while keeping window.use() as the displayed text. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@serhiy-storchaka Hello again, I’d like to report an issue. I found test_curses fails during setUp() when running with nohup:

Traceback (most recent call last):
  File "/root/cpython/Lib/test/test_curses.py", line 170, in setUp
    self.screen = curses.newterm(term, stdout_fd, infd)
                  ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "/root/cpython/Lib/curses/__init__.py", line 48, in newterm
    screen = _curses.newterm(type, fd, infd)
OSError: [Errno 22] Invalid argument

I have done some research: here _curses.newterm() needs a readable infd (input file descriptor). However, when the test is run with nohup, stdin is redirected to a write-only file, which causes the error. Although buildbots do not run the tests with nohup, it's quite common when running tests manually (to place long-running tasks in the background), so I think this is worth fixing.

My proposed fix is to additionally check whether sys.__stdin__.fileno() is write-only. If it is, we should follow the existing error-handling path ---- use stdout_fd instead. I tested this locally, and the fix works for me.

             try:
                 infd = sys.__stdin__.fileno()
+                import fcntl
+                if fcntl.fcntl(infd, fcntl.F_GETFL) & os.O_ACCMODE == os.O_WRONLY:
+                    raise OSError
             except (AttributeError, ValueError, OSError):
                 infd = stdout_fd

How to reproduce:

I'm using fedora:rawhide image. Run the test with:

LD_LIBRARY_PATH=/root/cpython nohup ./python -m test test_curses -uall -j1 &

Note that this can't be reproduced even with the latest Ubuntu image, because its ncurses version is not new enough. It uses ncurses 6.4 so does not take the USE_NEWTERM branch.

Thanks for the report and the diagnosis! Fixed in #153420.

Thanks for the report and the diagnosis! Fixed in #153420.

Thanks for the quick fix! I’ve confirmed that #153420 addresses the issue.

serhiy-storchaka requested review from AA-Turner, corona10, emmatyping, erlend-aasland and itamaro as code owners June 19, 2026 19:08

bedevere-app Bot mentioned this pull request Jun 19, 2026

python curses newterm implementation #90092

Closed

bedevere-app Bot added the awaiting core review label Jun 19, 2026

StanFromIreland reviewed Jun 19, 2026

View reviewed changes

serhiy-storchaka mentioned this pull request Jun 20, 2026

gh-87904: Document curses classes #151643

Merged

serhiy-storchaka force-pushed the curses-newterm branch from 25df3f0 to 3be2f8f Compare June 20, 2026 06:59

serhiy-storchaka force-pushed the curses-newterm branch from 3be2f8f to d27487e Compare June 20, 2026 07:06

serhiy-storchaka and others added 7 commits June 20, 2026 10:50

Merge branch 'main' into curses-newterm

fd73570

# Conflicts: # Doc/whatsnew/3.16.rst # Modules/clinic/_cursesmodule.c.h

serhiy-storchaka enabled auto-merge (squash) June 24, 2026 11:00

serhiy-storchaka force-pushed the curses-newterm branch from 1b1ec6e to 86d808e Compare June 24, 2026 11:03

serhiy-storchaka merged commit ac023ea into python:main Jun 24, 2026
55 checks passed

bedevere-app Bot removed the awaiting core review label Jun 24, 2026

serhiy-storchaka deleted the curses-newterm branch July 1, 2026 16:47

picnixz mentioned this pull request Jul 4, 2026

Build error by using stdscr in curses C extension module #153009

Closed

fedonman mentioned this pull request Sep 4, 2026

gh-156953: Fix a reference leak in curses window.insnstr() #156954

Merged

gh-90092: Support multiple terminals in the curses module by serhiy-storchaka · Pull Request #151748 · python/cpython · GitHub

Repository navigation

gh-90092: Support multiple terminals in the curses module - #151748

gh-90092: Support multiple terminals in the curses module#151748
serhiy-storchaka merged 10 commits into
python:mainfrom
serhiy-storchaka:curses-newterm

serhiy-storchaka commented Jun 19, 2026 •
edited by bedevere-app Bot
Loading

Uh oh!

Uh oh!

read-the-docs-community Bot commented Jun 19, 2026 •
edited
Loading

Uh oh!

Uh oh!

StanFromIreland Jun 19, 2026

Uh oh!

serhiy-storchaka Jun 19, 2026

Uh oh!

serhiy-storchaka commented Jun 19, 2026

Uh oh!

Uh oh!

weixlu commented Jul 9, 2026

Uh oh!

weixlu commented Jul 9, 2026

Uh oh!

serhiy-storchaka commented Jul 9, 2026

Uh oh!

weixlu commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

+                 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()``.

gh-90092: Support multiple terminals in the curses module by serhiy-storchaka · Pull Request #151748 · python/cpython · GitHub

Repository navigation

gh-90092: Support multiple terminals in the curses module - #151748

gh-90092: Support multiple terminals in the curses module#151748serhiy-storchaka merged 10 commits intopython:mainpython/cpython:mainfrom serhiy-storchaka:curses-newtermserhiy-storchaka/cpython:curses-newtermCopy head branch name to clipboard

Conversation

serhiy-storchaka commented Jun 19, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

StanFromIreland Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka commented Jun 19, 2026

Uh oh!

Uh oh!

weixlu commented Jul 9, 2026

Uh oh!

weixlu commented Jul 9, 2026

Uh oh!

serhiy-storchaka commented Jul 9, 2026

Uh oh!

weixlu commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gh-90092: Support multiple terminals in the curses module#151748
serhiy-storchaka merged 10 commits into
python:mainfrom
serhiy-storchaka:curses-newterm

serhiy-storchaka commented Jun 19, 2026 •
edited by bedevere-app Bot
Loading

read-the-docs-community Bot commented Jun 19, 2026 •
edited
Loading