Add screen.close() to break the screen/window reference cycle

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>

Author: serhiy-storchaka

Doc/library/curses.rst

@@ -1462,6 +1462,20 @@ Screen objects
    .. 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,

Lib/test/test_curses.py

@@ -124,11 +124,12 @@ def setUp(self):
                 infd = stdout_fd
             self.screen = curses.newterm(term, stdout_fd, infd)
             self.stdscr = self.screen.stdscr
-            # Drop the screen after the test, and collect the window<->screen
-            # reference cycle while the screen is still current, so delwin()
-            # succeeds; collected later, on a non-current screen, it fails
-            # (unraisable on macOS).
-            self.addCleanup(gc_collect)
+            # Close the screen after the test: it breaks the window<->screen
+            # reference cycle and detaches the standard window so its delwin()
+            # is skipped.  Otherwise the window is collected during a later test
+            # whose screen is no longer current, and delwin() fails (unraisable
+            # on macOS).
+            self.addCleanup(self.screen.close)
             self.addCleanup(setattr, self, 'screen', None)
             self.addCleanup(setattr, self, 'stdscr', None)
         else:
@@ -1869,6 +1870,19 @@ def test_screen_freed(self):
         del a
         gc_collect()
 
+    def test_close(self):
+        s = self.make_pty()
+        screen = curses.newterm('xterm', s, s)
+        win = screen.stdscr
+        self.assertIsInstance(win, curses.window)
+        screen.close()
+        # After close() the standard window is detached and unusable, and
+        # stdscr is None.  No reference cycle remains.
+        self.assertIsNone(screen.stdscr)
+        self.assertRaises(curses.error, win.addstr, 0, 0, 'x')
+        # close() is idempotent.
+        screen.close()
+
     @unittest.skipUnless(hasattr(curses, 'new_prescr'),
                          'requires curses.new_prescr()')
     def test_new_prescr(self):

Modules/_cursesmodule.c

@@ -3339,7 +3339,23 @@ PyCursesScreen_use(PyObject *self, PyObject *args, PyObject *kwargs)
 }
 #endif /* HAVE_CURSES_USE_SCREEN */
 
+PyDoc_STRVAR(PyCursesScreen_close__doc__,
+"close($self, /)\n--\n\n"
+"Detach the screen's standard window, breaking their reference cycle.\n\n"
+"Afterwards the stdscr attribute is None and the window it returned earlier\n"
+"can no longer be used.  The screen is released once it and its windows are\n"
+"no longer referenced.");
+
+static PyObject *
+PyCursesScreen_close(PyObject *self, PyObject *Py_UNUSED(ignored))
+{
+    (void)PyCursesScreen_clear(self);
+    Py_RETURN_NONE;
+}
+
 static PyMethodDef PyCursesScreen_methods[] = {
+    {"close", PyCursesScreen_close, METH_NOARGS,
+     PyCursesScreen_close__doc__},
 #ifdef HAVE_CURSES_USE_SCREEN
     {"use", _PyCFunction_CAST(PyCursesScreen_use),
      METH_VARARGS | METH_KEYWORDS, PyCursesScreen_use__doc__},