[3.15] gh-144067: Document terminal leak when initscr() follows setupterm() (GH-15262...

(cherry picked from commit e471712958515b65b737ac742b294acf7de9220c)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index 621e3d6ad2043a023494889c8aba17b16fb6d5f2..f2115a236f258328937684e95700278bd1f6bf41 100644 (file)
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -324,6 +324,8 @@ The module :mod:`!curses` defines the following functions:
    Initialize the library. Return a :ref:`window <curses-window-objects>` object
    which represents the whole screen.
 
+   See :func:`setupterm` for a caveat about calling it before this function.
+
    .. note::
 
       If there is an error opening the terminal, the underlying curses library may
@@ -593,6 +595,13 @@ The module :mod:`!curses` defines the following functions:
    terminfo database entry could not be read.  If the terminal has already
    been initialized, this function has no effect.
 
+   .. note::
+
+      Calling :func:`initscr` after :func:`setupterm`
+      leaks the terminal that :func:`setupterm` allocated:
+      the curses library keeps only a single current terminal
+      and does not free the previously allocated one.
+
 
 .. function:: start_color()