Merge remote-tracking branch 'upstream/main' into clinic-groups-inline

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

Author: serhiy-storchaka

.github/CODEOWNERS

@@ -620,6 +620,12 @@ Lib/test/test_unittest/testmock/ @cjw296
 # Weakref
 **/*weakref*                  @kumaraditya303
 
+# Zlib
+Doc/library/zlib.rst          @StanFromIreland
+Lib/compression/zlib.py       @StanFromIreland
+Lib/test/test_zlib.py         @StanFromIreland
+Modules/_zlibmodule.c         @StanFromIreland
+
 # Zipfile.Path
 Lib/test/test_zipfile/_path/  @jaraco
 Lib/zipfile/_path/            @jaraco

Doc/glossary.rst

@@ -509,7 +509,7 @@ Glossary
       A piece of syntax which can be evaluated to some value.  In other words,
       an expression is an accumulation of expression elements like literals,
       names, attribute access, operators or function calls which all return a
-      value.  In contrast to many other languages, not all language constructs
+      value.  Not all language constructs
       are expressions.  There are also :term:`statement`\s which cannot be used
       as expressions, such as :keyword:`while`.  Assignments are also statements,
       not expressions.

Doc/library/asyncio-stream.rst

@@ -49,7 +49,7 @@ and work with streams:
 
 
 .. function:: open_connection(host=None, port=None, *, \
-                 limit=None, ssl=None, family=0, proto=0, \
+                 limit=65536, ssl=None, family=0, proto=0, \
                  flags=0, sock=None, local_addr=None, \
                  server_hostname=None, ssl_handshake_timeout=None, \
                  ssl_shutdown_timeout=None, \
@@ -89,7 +89,7 @@ and work with streams:
 
 
 .. function:: start_server(client_connected_cb, host=None, \
-                 port=None, *, limit=None, \
+                 port=None, *, limit=65536, \
                  family=socket.AF_UNSPEC, \
                  flags=socket.AI_PASSIVE, sock=None, \
                  backlog=100, ssl=None, reuse_address=None, \
@@ -137,7 +137,7 @@ and work with streams:
 
 .. rubric:: Unix Sockets
 
-.. function:: open_unix_connection(path=None, *, limit=None, \
+.. function:: open_unix_connection(path=None, *, limit=65536, \
                ssl=None, sock=None, server_hostname=None, \
                ssl_handshake_timeout=None, ssl_shutdown_timeout=None)
    :async:
@@ -169,7 +169,7 @@ and work with streams:
 
 
 .. function:: start_unix_server(client_connected_cb, path=None, \
-                 *, limit=None, sock=None, backlog=100, ssl=None, \
+                 *, limit=65536, sock=None, backlog=100, ssl=None, \
                  ssl_handshake_timeout=None, \
                  ssl_shutdown_timeout=None, start_serving=True, \
                  cleanup_socket=True, mode=None)

Doc/library/asyncio-subprocess.rst

@@ -62,7 +62,7 @@ Creating Subprocesses
 =====================
 
 .. function:: create_subprocess_exec(program, *args, stdin=None, \
-                 stdout=None, stderr=None, limit=None, **kwds)
+                 stdout=None, stderr=None, limit=65536, **kwds)
    :async:
 
    Create a subprocess.
@@ -84,7 +84,7 @@ Creating Subprocesses
 
 
 .. function:: create_subprocess_shell(cmd, stdin=None, \
-                 stdout=None, stderr=None, limit=None, **kwds)
+                 stdout=None, stderr=None, limit=65536, **kwds)
    :async:
 
    Run the *cmd* shell command.

Doc/library/curses.rst

@@ -27,9 +27,15 @@ Linux and the BSD variants of Unix.
 
    Whenever the documentation mentions a *character* it can be specified
    as an integer, a one-character Unicode string or a one-byte byte string.
+   An integer is the code of a single encoded byte, optionally combined with
+   attributes and a color pair, as returned by :meth:`window.inch`.
+   Methods that write to a window accept also a character cell: a Unicode
+   string of a spacing character followed by combining characters, or a
+   :class:`complexchar`.
 
    Whenever the documentation mentions a *character string* it can be specified
    as a Unicode string or a byte string.
+   Methods that write to a window accept also a :class:`complexstr`.
 
 .. note::
 
@@ -364,9 +370,9 @@ Keyboard input
    Push *ch* so the next :meth:`~window.getch` or :meth:`~window.get_wch` will
    return it.
 
-   *ch* may be an integer (a key code or character code), a byte, or a string of
-   length 1.  A one-character string is pushed like :func:`unget_wch`; on a
-   narrow build it must encode to a single byte.
+   *ch* may be an integer (a key code or the code of an encoded byte), a byte,
+   or a string of length 1.  A one-character string is pushed like
+   :func:`unget_wch`; on a narrow build it must encode to a single byte.
 
    .. note::
 
@@ -380,6 +386,9 @@ Keyboard input
 
    Push *ch* so the next :meth:`~window.get_wch` will return it.
 
+   *ch* may be an integer (a character code, not a key code) or a string of
+   length 1.
+
    .. note::
 
       Only one *ch* can be pushed before :meth:`!get_wch` is called.
@@ -1015,7 +1024,7 @@ Terminfo database
 .. function:: tparm(str[, ...])
 
    Instantiate the bytes object *str* with the supplied parameters, where *str* should
-   be a parameterized string obtained from the terminfo database.  For example,
+   be a parameterized byte string obtained from the terminfo database.  For example,
    ``tparm(tigetstr("cup"), 5, 3)`` could result in ``b'\033[6;4H'``, the exact
    result depending on terminal type.  Up to nine integer parameters may be supplied.
 
@@ -1024,8 +1033,8 @@ Terminfo database
 .. function:: putp(str)
 
    Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified
-   terminfo capability for the current terminal.  Note that the output of :func:`putp`
-   always goes to standard output.
+   terminfo capability, a bytes object, for the current terminal.
+   Note that the output of :func:`putp` always goes to standard output.
 
    :func:`setupterm` (or :func:`initscr`) must be called first.
 
@@ -1035,9 +1044,15 @@ Utilities
 
 .. function:: unctrl(ch)
 
-   Return a bytes object which is a printable representation of the character *ch*.
-   *ch* cannot be a character that does not fit in a single byte; use
-   :func:`wunctrl` for those.
+   Return a bytes object which is a printable representation of the character *ch*;
+   any attributes and color pair are ignored.
+   Control characters are represented as a caret followed by a character,
+   for example as ``b'^C'``.
+   Printing characters are left as they are.
+   The representation of other characters is defined by the underlying curses
+   library.
+
+   *ch* must fit in a single byte; use :func:`wunctrl` for other characters.
 
 .. function:: wunctrl(ch)
 
@@ -1264,19 +1279,47 @@ Reading input
 
 .. method:: window.getch([y, x])
 
-   Get a character. Note that the integer returned does *not* have to be in ASCII
-   range: function keys, keypad keys and so on are represented by numbers higher
-   than 255.  In no-delay mode, return ``-1`` if there is no input, otherwise
-   wait until a key is pressed.
-   A multibyte character is returned as its encoded bytes one at a time; use
-   :meth:`get_wch` to read it as a single character.
+   Read a key press, after moving the cursor to *y*, *x* if specified,
+   and return it as an integer.
+   The window is refreshed first if it is not a pad and was modified since
+   the last refresh.
+   Wait until a key is pressed, or return ``-1`` if the read is non-blocking
+   or times out (see :meth:`nodelay` and :meth:`timeout`).
+
+   An ordinary key is returned as the code of a single byte of its encoding
+   in the current locale,
+   so a character encoded with several bytes takes several calls.
+   For example, in a UTF-8 locale ``'é'`` is read as ``195``, then ``169``.
+   Use :meth:`get_wch` to read it as a single character.
+
+   In keypad mode (see :meth:`keypad`) function keys and other special keys
+   are returned as one of the :ref:`KEY_* constants <curses-key-constants>`,
+   which cannot be mistaken for an ordinary key.
+   Otherwise, or if their escape sequence does not arrive in time
+   (see :meth:`notimeout` and :func:`set_escdelay`),
+   their bytes are returned one at a time.
+
+   In echo mode (see :func:`echo`) the key is added to the window as by
+   :meth:`addch`; special keys are not echoed.
 
 .. method:: window.get_wch([y, x])
 
-   Get a wide character. Return a character for most keys, or an integer for
-   function keys, keypad keys, and other special keys.  Unlike :meth:`getch`, an
-   ordinary key is returned as a one-character :class:`str`.
-   In no-delay mode, raise an exception if there is no input.
+   Read a key press, after moving the cursor to *y*, *x* if specified,
+   and return it as a one-character :class:`str`.
+   The window is refreshed first if it is not a pad and was modified since
+   the last refresh.
+   Wait until a key is pressed, or raise :exc:`error` if the read is
+   non-blocking or times out (see :meth:`nodelay` and :meth:`timeout`).
+
+   In keypad mode (see :meth:`keypad`) function keys and other special keys
+   are returned as one of the :ref:`KEY_* constants <curses-key-constants>`,
+   an integer.
+   Otherwise, or if their escape sequence does not arrive in time
+   (see :meth:`notimeout` and :func:`set_escdelay`),
+   their characters are returned one at a time.
+
+   In echo mode (see :func:`echo`) the key is added to the window as by
+   :meth:`addch`; special keys are not echoed.
 
    .. versionadded:: 3.3
 
@@ -1286,21 +1329,24 @@ Reading input
 
 .. method:: window.getkey([y, x])
 
-   Get a character, returning a string instead of an integer, as :meth:`getch`
-   does. Function keys, keypad keys and other special keys return a multibyte
-   string containing the key name.  In no-delay mode, raise an exception if
-   there is no input.
+   Read a key press as :meth:`getch` does, but return it as a :class:`str`:
+   an ordinary key as a one-character string, the byte decoded as Latin-1,
+   and a special key as its name, such as ``'KEY_UP'`` (see :func:`keyname`).
+   Raise :exc:`error` instead of returning ``-1`` if there is no input.
 
 .. method:: window.getstr()
             window.getstr(n)
             window.getstr(y, x)
             window.getstr(y, x, n)
 
-   Read a bytes object from the user, with primitive line editing capacity.
-   At most *n* characters are read;
+   Read a line of input from the user, with primitive line editing capacity,
+   after moving the cursor to *y*, *x* if specified.
+   Return it as a bytes object, in the encoding of the current locale
+   and without the terminating newline.
+   At most *n* bytes are read;
    *n* defaults to and cannot exceed 2047.
-   A multibyte character is returned as its encoded bytes; use :meth:`get_wstr`
-   to read the input as a :class:`str`.
+
+   Use :meth:`get_wstr` to read the input as a :class:`str`.
 
    .. versionchanged:: 3.14
       The maximum value for *n* was increased from 1023 to 2047.
@@ -1310,10 +1356,13 @@ Reading input
             window.get_wstr(y, x)
             window.get_wstr(y, x, n)
 
-   Read a string from the user, with primitive line editing capacity.
-   Unlike :meth:`getstr`, it can return characters that are not representable in
-   the window's encoding.
-   At most *n* characters are read; *n* defaults to and cannot exceed 2047.
+   Read a line of input from the user, with primitive line editing capacity,
+   after moving the cursor to *y*, *x* if specified.
+   Return it as a :class:`str`, without the terminating newline.
+   At most *n* characters are read;
+   *n* defaults to and cannot exceed 2047.
+
+   This is the wide-character variant of :meth:`getstr`.
 
    .. versionadded:: next
 
@@ -1354,13 +1403,13 @@ Reading window contents
 .. method:: window.instr([n])
             window.instr(y, x[, n])
 
-   Return a bytes object of characters, extracted from the window starting at the
-   current cursor position, or at *y*, *x* if specified, and stopping at the end
-   of the line. Attributes and color information are stripped
-   from the characters.  If *n* is specified, :meth:`instr` returns a string
-   at most *n* characters long (exclusive of the trailing NUL).
-   The maximum value for *n* is 2047.
-   A character not representable in the window's encoding cannot be returned;
+   Read the text of the window from the current cursor position,
+   or from *y*, *x* if specified, to the end of the line,
+   and return it as a bytes object, in the encoding of the current locale.
+   Attributes and color pairs are stripped;
+   use :meth:`in_wchstr` to read them too.
+   At most *n* bytes are read; *n* defaults to and cannot exceed 2047.
+   A character not representable in the encoding cannot be returned;
    use :meth:`in_wstr` for those.
 
    .. versionchanged:: 3.14
@@ -1369,26 +1418,27 @@ Reading window contents
 .. method:: window.in_wstr([n])
             window.in_wstr(y, x[, n])
 
-   Return a string of characters, extracted from the window starting at the
-   current cursor position, or at *y*, *x* if specified.  Unlike :meth:`instr`,
-   it can return characters that are not representable in the window's encoding.
-   Attributes and color information are stripped from the characters.  The
-   maximum value for *n* is 2047.
+   Read the text of the window from the current cursor position,
+   or from *y*, *x* if specified, to the end of the line,
+   and return it as a :class:`str`.
+   Attributes and color pairs are stripped;
+   use :meth:`in_wchstr` to read them too.
+   At most *n* characters are read; *n* defaults to and cannot exceed 2047.
+
+   This is the wide-character variant of :meth:`instr`.
 
    .. versionadded:: next
 
 .. method:: window.in_wchstr([n])
             window.in_wchstr(y, x[, n])
 
-   Return a :class:`complexstr` of the styled cells extracted from the window
-   starting at the current cursor position, or at *y*, *x* if specified, and
-   stopping at the end of the line.  This is the variant of :meth:`instr` and
-   :meth:`in_wstr` that *keeps* each cell's attributes and color pair (those
-   methods strip the rendition).  If *n* is specified, at most *n* cells are
-   returned.  The maximum value for *n* is 2047.
-
-   The result can be written back unchanged with :meth:`addstr` (a read and a
-   re-write is a round-trip that preserves every cell's rendition).
+   Read the styled cells of the window from the current cursor position,
+   or from *y*, *x* if specified, to the end of the line,
+   and return them as a :class:`complexstr`.
+   Unlike :meth:`instr` and :meth:`in_wstr`, each cell keeps its attributes
+   and color pair, so the result can be written back unchanged
+   with :meth:`addstr`.
+   At most *n* cells are read; *n* defaults to and cannot exceed 2047.
 
    .. versionadded:: next
 
@@ -1835,6 +1885,8 @@ Input options
    If *flag* is ``True``, escape sequences generated by some keys (keypad,  function keys)
    will be interpreted by :mod:`!curses`. If *flag* is ``False``, escape sequences will be
    left as is in the input stream.
+   Keypad mode is disabled by default, but :func:`wrapper` enables it for the
+   main window.
 
 .. method:: window.nodelay(flag)
 
@@ -2331,6 +2383,8 @@ by some methods.
 | .. data:: A_COLOR       |                          | Bit-mask to extract color-pair field information |
 +-------------------------+--------------------------+--------------------------------------------------+
 
+.. _curses-key-constants:
+
 Keys
 ~~~~