[3.12] gh-107008: Document the curses module variables LINES and COLS (GH-107011)

Doc/library/curses.rst

@@ -176,7 +176,7 @@
 
 .. function:: filter()
 
    The :func:`.filter` routine, if used, must be called before :func:`initscr` is
    called.  The effect is that, during those calls, :envvar:`LINES` is set to ``1``; the
    capabilities ``clear``, ``cup``, ``cud``, ``cud1``, ``cuu1``, ``cuu``, ``vpa`` are disabled; and the ``home``
    string is set to the value of ``cr``. The effect is that the cursor is confined to
@@ -546,7 +546,7 @@
 
 .. function:: setupterm(term=None, fd=-1)
 
    Initialize the terminal.  *term* is a string giving
    the terminal name, or ``None``; if omitted or ``None``, the value of the
    :envvar:`TERM` environment variable will be used.  *fd* is the
    file descriptor to which any initialization sequences will be sent; if not
@@ -575,7 +575,7 @@
 
 .. function:: termname()
 
    Return the value of the environment variable :envvar:`TERM`, as a bytes object,
    truncated to 14 characters.
 
 
@@ -641,7 +641,8 @@
 
 .. function:: update_lines_cols()
 
-   Update :envvar:`LINES` and :envvar:`COLS`. Useful for detecting manual screen resize.
+   Update the :const:`LINES` and :const:`COLS` module variables.
+   Useful for detecting manual screen resize.
 
    .. versionadded:: 3.5
 
@@ -665,7 +666,7 @@
 
 .. function:: use_env(flag)
 
    If used, this function should be called before :func:`initscr` or newterm are
    called.  When *flag* is ``False``, the values of lines and columns specified in the
    terminfo database will be used, even if environment variables :envvar:`LINES`
    and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a
@@ -1342,10 +1343,27 @@
 .. data:: COLORS
 
    The maximum number of colors the terminal can support.
+   It is defined only after the call to :func:`start_color`.
 
 .. data:: COLOR_PAIRS
 
    The maximum number of color pairs the terminal can support.
+   It is defined only after the call to :func:`start_color`.
+
+.. data:: COLS
+
+   The width of the screen, i.e., the number of columns.
+   It is defined only after the call to :func:`initscr`.
+   Updated by :func:`update_lines_cols`, :func:`resizeterm` and
+   :func:`resize_term`.
+
+.. data:: LINES
+
+   The height of the screen, i.e., the number of lines.
+   It is defined only after the call to :func:`initscr`.
+   Updated by :func:`update_lines_cols`, :func:`resizeterm` and
+   :func:`resize_term`.
+
 
 Some constants are available to specify character cell attributes.
 The exact constants available are system dependent.

Doc/whatsnew/3.5.rst

@@ -178,7 +178,7 @@
     >>> async def coro():
     ...     return 'spam'
 
 Inside a coroutine function, the new :keyword:`await` expression can be used
 to suspend coroutine execution until the result is available.  Any object
 can be *awaited*, as long as it implements the :term:`awaitable` protocol by
 defining the :meth:`__await__` method.
@@ -271,7 +271,7 @@
 PEP 465 - A dedicated infix operator for matrix multiplication
 --------------------------------------------------------------
 
 :pep:`465` adds the ``@`` infix operator for matrix multiplication.
 Currently, no builtin Python types implement the new operator, however, it
 can be implemented by defining :meth:`__matmul__`, :meth:`__rmatmul__`,
 and :meth:`__imatmul__` for regular, reflected, and in-place matrix
@@ -1045,8 +1045,8 @@
 curses
 ------
 
-The new :func:`~curses.update_lines_cols` function updates the :envvar:`LINES`
-and :envvar:`COLS` environment variables.  This is useful for detecting
+The new :func:`~curses.update_lines_cols` function updates the :data:`LINES`
+and :data:`COLS` module variables.  This is useful for detecting
 manual screen resizing.  (Contributed by Arnon Yaari in :issue:`4254`.)
 
 

Misc/NEWS.d/next/Documentation/2023-07-22-15-14-13.gh-issue-107008.3JQ1Vt.rst

@@ -0,0 +1,2 @@
+Document the :mod:`curses` module variables :const:`~curses.LINES` and
+:const:`~curses.COLS`.