Merge remote-tracking branch 'upstream/main' into curses-chtype-overflow

# Conflicts:
#	Modules/clinic/_cursesmodule.c.h

Author: serhiy-storchaka

Doc/deprecations/soft-deprecations.rst

@@ -19,3 +19,8 @@ There are no plans to remove :term:`soft deprecated` APIs.
 
   (Contributed by Gregory P. Smith in :gh:`86519` and
   Hugo van Kemenade in :gh:`148100`.)
+
+* Using ``'F'`` and ``'D'`` format type codes of the :mod:`struct` module
+  now are :term:`soft deprecated` in favor of two-letter forms ``'Zf'``
+  and ``'Zd'``.
+  (Contributed by Sergey B Kirpichev in :gh:`121249`.)

Doc/library/curses.rst

@@ -699,6 +699,40 @@ The module :mod:`!curses` defines the following functions:
    Save the current state of the terminal modes in a buffer, usable by
    :func:`resetty`.
 
+.. function:: scr_dump(filename)
+
+   Write the current contents of the virtual screen to *filename*, which may be
+   a string or a :term:`path-like object`.  The file can later be read by
+   :func:`scr_restore`, :func:`scr_init` or :func:`scr_set`.  This is the
+   whole-screen counterpart of :meth:`window.putwin`.
+
+   .. versionadded:: next
+
+.. function:: scr_restore(filename)
+
+   Set the virtual screen to the contents of *filename*, which must have been
+   written by :func:`scr_dump`.  The next call to :func:`doupdate` or
+   :meth:`window.refresh` restores the screen to those contents.
+
+   .. versionadded:: next
+
+.. function:: scr_init(filename)
+
+   Initialize the assumed contents of the terminal from *filename*, which must
+   have been written by :func:`scr_dump`.  Use it when the terminal already
+   displays those contents, for example after another program has drawn the
+   screen, so that curses does not redraw what is already there.
+
+   .. versionadded:: next
+
+.. function:: scr_set(filename)
+
+   Use *filename*, which must have been written by :func:`scr_dump`, as both
+   the virtual screen and the assumed terminal contents.  This combines the
+   effects of :func:`scr_restore` and :func:`scr_init`.
+
+   .. versionadded:: next
+
 .. function:: get_escdelay()
 
    Retrieves the value set by :func:`set_escdelay`.
@@ -1195,6 +1229,17 @@ Window objects
    object for the derived window.
 
 
+.. method:: window.dupwin()
+
+   Return a new window that is an exact duplicate of the window: it has the same
+   size, position, contents and attributes.  Unlike a window created by
+   :meth:`subwin` or :meth:`derwin`, the duplicate is independent of the
+   original -- it has its own cell buffer, so later changes to one do not affect
+   the other.
+
+   .. versionadded:: next
+
+
 .. method:: window.echochar(ch[, attr])
 
    Add character *ch* with attribute *attr*, and immediately  call :meth:`refresh`

Doc/library/struct.rst

@@ -261,10 +261,6 @@ platform-dependent.
 +--------+--------------------------+--------------------+----------------+------------+
 | ``d``  | :c:expr:`double`         | float              | 8              | \(4)       |
 +--------+--------------------------+--------------------+----------------+------------+
-| ``F``  | :c:expr:`float complex`  | complex            | 8              | \(10)      |
-+--------+--------------------------+--------------------+----------------+------------+
-| ``D``  | :c:expr:`double complex` | complex            | 16             | \(10)      |
-+--------+--------------------------+--------------------+----------------+------------+
 | ``Zf`` | :c:expr:`float complex`  | complex            | 8              | \(10)      |
 +--------+--------------------------+--------------------+----------------+------------+
 | ``Zd`` | :c:expr:`double complex` | complex            | 16             | \(10)      |
@@ -287,6 +283,7 @@ platform-dependent.
 
 .. versionchanged:: 3.15
    Added support for the ``'Zf'`` and ``'Zd'`` formats.
+   ``'F'`` and ``'D'`` formats are :term:`soft deprecated`.
 
 .. seealso::
 
@@ -377,13 +374,15 @@ Notes:
    are accepted.
 
 (10)
-   For the ``'F'`` and ``'D'`` type codes, the packed representation uses
+   For the ``'Zf'`` and ``'Zd'`` type codes, the packed representation uses
    the IEEE 754 binary32 and binary64 format for components of the complex
    number, regardless of the floating-point format used by the platform.
-   Note that complex types (``F``/``Zf`` and ``D``/``Zd``) are available unconditionally,
+   Note that complex types are available unconditionally,
    despite complex types being an optional feature in C.
    As specified in the C11 standard, each complex type is represented by a
    two-element C array containing, respectively, the real and imaginary parts.
+   The ``'F'`` and ``'D'`` (for ``'Zf'`` and ``'Zd'``, respectively) format
+   characters are supported for compatibility.
 
 
 A type code may be preceded by an integral repeat count.  For example,

Doc/whatsnew/3.15.rst

@@ -2280,6 +2280,11 @@ New deprecations
 
     (Contributed by Sergey B Kirpichev and Serhiy Storchaka in :gh:`143715`.)
 
+  * Using ``'F'`` and ``'D'`` type codes now are :term:`soft deprecated`
+    in favor of two-letter forms ``'Zf'`` and ``'Zd'``.
+    (Contributed by Sergey B Kirpichev in :gh:`121249`.)
+
+
 * :mod:`typing`:
 
   * The following statements now cause ``DeprecationWarning``\ s to be emitted

Doc/whatsnew/3.16.rst

@@ -156,6 +156,15 @@ curses
   accept a :class:`~curses.complexstr`.
   (Contributed by Serhiy Storchaka in :gh:`152233`.)
 
+* Add the :mod:`curses` window method :meth:`~curses.window.dupwin`, which
+  returns a new window that is an independent duplicate of an existing one.
+  (Contributed by Serhiy Storchaka in :gh:`152258`.)
+
+* Add the :mod:`curses` functions :func:`~curses.scr_dump`,
+  :func:`~curses.scr_restore`, :func:`~curses.scr_init` and
+  :func:`~curses.scr_set`, which dump the whole screen to a file and restore it.
+  (Contributed by Serhiy Storchaka in :gh:`152260`.)
+
 gzip
 ----
 

Lib/test/support/__init__.py

@@ -35,7 +35,7 @@
     "requires_gil_enabled", "requires_linux_version", "requires_mac_ver",
     "check_syntax_error",
     "requires_gzip", "requires_bz2", "requires_lzma", "requires_zstd",
-    "bigmemtest", "bigaddrspacetest", "cpython_only", "get_attribute",
+    "bigmemtest", "nomemtest", "bigaddrspacetest", "cpython_only", "get_attribute",
     "requires_IEEE_754", "requires_zlib",
     "has_fork_support", "requires_fork",
     "has_subprocess_support", "requires_subprocess",
@@ -1305,6 +1305,22 @@ def wrapper(self):
         return wrapper
     return decorator
 
+def nomemtest(f):
+    """Check that we can use this test with `_testcapi.set_nomemory`."""
+    from .import_helper import import_module
+
+    @functools.wraps(f)
+    def internal(*args, **kwargs):
+        import_module('_testcapi')
+        return f(*args, **kwargs)
+
+    return unittest.skipIf(
+        # Python built with Py_TRACE_REFS fail with a fatal error in
+        # _PyRefchain_Trace() on memory allocation error.
+        Py_TRACE_REFS,
+        'cannot test Py_TRACE_REFS build',
+    )(cpython_only(internal))
+
 def bigaddrspacetest(f):
     """Decorator for tests that fill the address space."""
     def wrapper(self):

Lib/test/test_atexit.py

@@ -191,9 +191,7 @@ def callback():
         self.assertEqual(os.read(r, len(expected)), expected)
         os.close(r)
 
-    # Python built with Py_TRACE_REFS fail with a fatal error in
-    # _PyRefchain_Trace() on memory allocation error.
-    @unittest.skipIf(support.Py_TRACE_REFS, 'cannot test Py_TRACE_REFS build')
+    @support.nomemtest
     def test_atexit_with_low_memory(self):
         # gh-140080: Test that setting low memory after registering an atexit
         # callback doesn't cause an infinite loop during finalization.

Lib/test/test_capi/test_mem.py

@@ -117,9 +117,7 @@ def test_pyobject_forbidden_bytes_is_freed(self):
     def test_pyobject_freed_is_freed(self):
         self.check_pyobject_is_freed('check_pyobject_freed_is_freed')
 
-    # Python built with Py_TRACE_REFS fail with a fatal error in
-    # _PyRefchain_Trace() on memory allocation error.
-    @unittest.skipIf(support.Py_TRACE_REFS, 'cannot test Py_TRACE_REFS build')
+    @support.nomemtest
     def test_set_nomemory(self):
         code = """if 1:
             import _testcapi

Lib/test/test_class.py

@@ -449,7 +449,6 @@ def __delattr__(self, *args):
 
     def testHasAttrString(self):
         import sys
-        from test.support import import_helper
         _testlimitedcapi = import_helper.import_module('_testlimitedcapi')
 
         class A:
@@ -1013,11 +1012,8 @@ class C:
         C.a = X()
         C.a = X()
 
-    @cpython_only
+    @support.nomemtest
     def test_detach_materialized_dict_no_memory(self):
-        # Skip test if _testcapi is not available:
-        import_helper.import_module('_testcapi')
-
         code = """if 1:
             import test.support
             import _testcapi

Lib/test/test_curses.py

@@ -218,6 +218,35 @@ def test_subwindows_references(self):
         del win2
         gc_collect()
 
+    def test_dupwin(self):
+        win = curses.newwin(5, 10, 2, 3)
+        win.addstr(0, 0, 'ABCDE')
+        win.addstr(1, 0, 'fghij')
+        dup = win.dupwin()
+        # Same geometry and contents as the original.
+        self.assertEqual(dup.getbegyx(), win.getbegyx())
+        self.assertEqual(dup.getmaxyx(), win.getmaxyx())
+        self.assertEqual(dup.instr(0, 0, 5), b'ABCDE')
+        self.assertEqual(dup.instr(1, 0, 5), b'fghij')
+        # The duplicate is independent, not a subwindow.
+        if hasattr(dup, 'is_subwin'):
+            self.assertIs(dup.is_subwin(), False)
+            self.assertIsNone(dup.getparent())
+        # Changes to one do not affect the other.
+        dup.addstr(0, 0, 'xxxxx')
+        win.addstr(1, 0, 'YYYYY')
+        self.assertEqual(win.instr(0, 0, 5), b'ABCDE')
+        self.assertEqual(dup.instr(0, 0, 5), b'xxxxx')
+        self.assertEqual(dup.instr(1, 0, 5), b'fghij')
+        self.assertEqual(win.instr(1, 0, 5), b'YYYYY')
+        # A subwindow can also be duplicated; the duplicate is independent.
+        sub = win.subwin(3, 5, 2, 3)
+        subdup = sub.dupwin()
+        self.assertEqual(subdup.getmaxyx(), sub.getmaxyx())
+        if hasattr(subdup, 'is_subwin'):
+            self.assertIs(subdup.is_subwin(), False)
+            self.assertIsNone(subdup.getparent())
+
     def test_move_cursor(self):
         stdscr = self.stdscr
         win = stdscr.subwin(10, 15, 2, 5)
@@ -1096,6 +1125,43 @@ def test_putwin(self):
             self.assertEqual(win.getmaxyx(), (5, 12))
             self.assertEqual(win.instr(2, 0), b' Lorem ipsum')
 
+    def test_scr_dump(self):
+        # Test scr_dump(), scr_restore(), scr_init() and scr_set().
+        # scr_dump() writes the virtual screen to a named file; the other three
+        # functions load it back.  The dumped image is internal curses state,
+        # not a window, so the round-trip is checked by comparing dump files
+        # rather than reading cells.
+        stdscr = self.stdscr
+        stdscr.erase()
+        stdscr.addstr(0, 0, 'screen dump test')
+        stdscr.refresh()
+        with tempfile.TemporaryDirectory() as d:
+            dump = os.path.join(d, 'dump')
+            self.assertIsNone(curses.scr_dump(dump))
+            # Dumping the same screen again is deterministic.
+            dump2 = os.path.join(d, 'dump2')
+            curses.scr_dump(dump2)
+            with open(dump, 'rb') as f1, open(dump2, 'rb') as f2:
+                self.assertEqual(f1.read(), f2.read())
+            # scr_restore() reloads that virtual screen, so dumping it again
+            # reproduces the original file even after the screen has changed.
+            stdscr.erase()
+            stdscr.addstr(0, 0, 'something else')
+            stdscr.refresh()
+            self.assertIsNone(curses.scr_restore(dump))
+            restored = os.path.join(d, 'restored')
+            curses.scr_dump(restored)
+            with open(dump, 'rb') as f1, open(restored, 'rb') as f2:
+                self.assertEqual(f1.read(), f2.read())
+            # scr_init() and scr_set() accept a dump file and return None.
+            self.assertIsNone(curses.scr_init(dump))
+            self.assertIsNone(curses.scr_set(dump))
+            # A bytes (path-like) filename is accepted too.
+            curses.scr_dump(os.fsencode(dump))
+            # Restoring from a missing file is an error.
+            self.assertRaises(curses.error,
+                              curses.scr_restore, os.path.join(d, 'nope'))
+
     def test_borders_and_lines(self):
         win = curses.newwin(5, 10, 5, 2)
         win.border('|', '!', '-', '_',
@@ -1339,8 +1405,6 @@ def test_state_getters(self):
         # Each is_*() getter returns the value set by the matching setter.
         for setter, getter in [
             ('clearok', 'is_cleared'),
-            ('idcok', 'is_idcok'),
-            ('idlok', 'is_idlok'),
             ('keypad', 'is_keypad'),
             ('leaveok', 'is_leaveok'),
             ('nodelay', 'is_nodelay'),
@@ -1351,6 +1415,19 @@ def test_state_getters(self):
             self.assertIs(getattr(stdscr, getter)(), True)
             getattr(stdscr, setter)(False)
             self.assertIs(getattr(stdscr, getter)(), False)
+
+        # idcok()/idlok() only take effect if the terminal can insert/delete
+        # characters/lines, so the getter reflects that capability.
+        stdscr.idcok(True)
+        self.assertIs(stdscr.is_idcok(), curses.has_ic())
+        stdscr.idcok(False)
+        self.assertIs(stdscr.is_idcok(), False)
+
+        stdscr.idlok(True)
+        self.assertIs(stdscr.is_idlok(),
+                      curses.has_il() or curses.tigetstr('csr') is not None)
+        stdscr.idlok(False)
+        self.assertIs(stdscr.is_idlok(), False)
         if hasattr(stdscr, 'immedok'):
             stdscr.immedok(True)
             self.assertIs(stdscr.is_immedok(), True)