Merge branch 'main' into docs/refwarn/whatsnew-3.4

Author: hugovk

Doc/glossary.rst

@@ -21,7 +21,9 @@ Glossary
         right delimiters (parentheses, square brackets, curly braces or triple
         quotes), or after specifying a decorator.
 
-      * The :const:`Ellipsis` built-in constant.
+      .. index:: single: ...; ellipsis literal
+
+      * The three dots form of the :ref:`Ellipsis <bltin-ellipsis-object>` object.
 
    abstract base class
       Abstract base classes complement :term:`duck-typing` by

Doc/howto/instrumentation.rst

@@ -269,6 +269,8 @@ should instead read:
 (assuming a :ref:`debug build <debug-build>` of CPython 3.6)
 
 
+.. _static-markers:
+
 Available static markers
 ------------------------
 

Doc/library/constants.rst

@@ -65,8 +65,9 @@ A small number of constants live in the built-in namespace.  They are:
 .. index:: single: ...; ellipsis literal
 .. data:: Ellipsis
 
-   The same as the ellipsis literal "``...``". Special value used mostly in conjunction
-   with extended slicing syntax for user-defined container data types.
+   The same as the ellipsis literal "``...``", an object frequently used to
+   indicate that something is omitted. Assignment to ``Ellipsis`` is possible, but
+   assignment to  ``...`` raises a :exc:`SyntaxError`.
    ``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type.
 
 

Doc/library/curses.rst

@@ -716,8 +716,10 @@ The module :mod:`curses` defines the following functions:
 Window Objects
 --------------
 
-Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
-the following methods and attributes:
+.. class:: window
+
+   Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
+   the following methods and attributes:
 
 
 .. method:: window.addch(ch[, attr])

Doc/library/hmac.rst

@@ -50,7 +50,9 @@ cannot be used with HMAC.
    .. versionadded:: 3.7
 
 
-An HMAC object has the following methods:
+.. class:: HMAC
+
+   An HMAC object has the following methods:
 
 .. method:: HMAC.update(msg)
 

Doc/library/mmap.rst

@@ -48,10 +48,11 @@ update the underlying file.
 
 To map anonymous memory, -1 should be passed as the fileno along with the length.
 
-.. class:: mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0)
+.. class:: mmap(fileno, length, tagname=None, \
+                access=ACCESS_DEFAULT, offset=0, *, trackfd=True)
 
    **(Windows version)** Maps *length* bytes from the file specified by the
-   file handle *fileno*, and creates a mmap object.  If *length* is larger
+   file descriptor *fileno*, and creates a mmap object.  If *length* is larger
    than the current size of the file, the file is extended to contain *length*
    bytes.  If *length* is ``0``, the maximum length of the map is the current
    size of the file, except that if the file is empty Windows raises an
@@ -69,6 +70,17 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
    will be relative to the offset from the beginning of the file. *offset*
    defaults to 0.  *offset* must be a multiple of the :const:`ALLOCATIONGRANULARITY`.
 
+   If *trackfd* is ``False``, the file handle corresponding to *fileno* will
+   not be duplicated, and the resulting :class:`!mmap` object will not
+   be associated with the map's underlying file.
+   This means that the :meth:`~mmap.mmap.size` and :meth:`~mmap.mmap.resize`
+   methods will fail.
+   This mode is useful to limit the number of open file handles.
+   The original file can be renamed (but not deleted) after closing *fileno*.
+
+   .. versionchanged:: next
+      The *trackfd* parameter was added.
+
    .. audit-event:: mmap.__new__ fileno,length,access,offset mmap.mmap
 
 .. class:: mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, \

Doc/library/shutil.rst

@@ -90,6 +90,13 @@ Directory and files operations
       copy the file more efficiently. See
       :ref:`shutil-platform-dependent-efficient-copy-operations` section.
 
+.. exception:: SpecialFileError
+
+   This exception is raised when :func:`copyfile` or :func:`copytree` attempt
+   to copy a named pipe.
+
+   .. versionadded:: 2.7
+
 .. exception:: SameFileError
 
    This exception is raised if source and destination in :func:`copyfile`

Doc/library/stdtypes.rst

@@ -5869,13 +5869,34 @@ It is written as ``None``.
 The Ellipsis Object
 -------------------
 
-This object is commonly used by slicing (see :ref:`slicings`).  It supports no
-special operations.  There is exactly one ellipsis object, named
+This object is commonly used used to indicate that something is omitted.
+It supports no special operations.  There is exactly one ellipsis object, named
 :const:`Ellipsis` (a built-in name).  ``type(Ellipsis)()`` produces the
 :const:`Ellipsis` singleton.
 
 It is written as ``Ellipsis`` or ``...``.
 
+In typical use, ``...`` as the ``Ellipsis`` object appears in a few different
+places, for instance:
+
+- In type annotations, such as :ref:`callable arguments <annotating-callables>`
+  or :ref:`tuple elements <annotating-tuples>`.
+
+- As the body of a function instead of a :ref:`pass statement <tut-pass>`.
+
+- In third-party libraries, such as `Numpy's slicing and striding
+  <https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding>`_.
+
+Python also uses three dots in ways that are not ``Ellipsis`` objects, for instance:
+
+- Doctest's :const:`ELLIPSIS <doctest.ELLIPSIS>`, as a pattern for missing content.
+
+- The default Python prompt of the :term:`interactive` shell when partial input is incomplete.
+
+Lastly, the Python documentation often uses three dots in conventional English
+usage to mean omitted content, even in code examples that also use them as the
+``Ellipsis``.
+
 
 .. _bltin-notimplemented-object:
 

Doc/library/typing.rst

@@ -230,9 +230,11 @@ For example:
 
    callback: Callable[[str], Awaitable[None]] = on_update
 
+.. index:: single: ...; ellipsis literal
+
 The subscription syntax must always be used with exactly two values: the
 argument list and the return type.  The argument list must be a list of types,
-a :class:`ParamSpec`, :data:`Concatenate`, or an ellipsis. The return type must
+a :class:`ParamSpec`, :data:`Concatenate`, or an ellipsis (``...``). The return type must
 be a single type.
 
 If a literal ellipsis ``...`` is given as the argument list, it indicates that
@@ -375,8 +377,11 @@ accepts *any number* of type arguments::
    # but ``z`` has been assigned to a tuple of length 3
    z: tuple[int] = (1, 2, 3)
 
+.. index:: single: ...; ellipsis literal
+
 To denote a tuple which could be of *any* length, and in which all elements are
-of the same type ``T``, use ``tuple[T, ...]``. To denote an empty tuple, use
+of the same type ``T``, use the literal ellipsis ``...``: ``tuple[T, ...]``.
+To denote an empty tuple, use
 ``tuple[()]``. Using plain ``tuple`` as an annotation is equivalent to using
 ``tuple[Any, ...]``::
 
@@ -1162,6 +1167,8 @@ These can be used as types in annotations. They all support subscription using
 
    Special form for annotating higher-order functions.
 
+   .. index:: single: ...; ellipsis literal
+
    ``Concatenate`` can be used in conjunction with :ref:`Callable <annotating-callables>` and
    :class:`ParamSpec` to annotate a higher-order callable which adds, removes,
    or transforms parameters of another

Doc/library/unittest.rst

@@ -2532,6 +2532,10 @@ instead of as an error.
 setUpModule and tearDownModule
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. function:: setUpModule
+              tearDownModule
+   :no-typesetting:
+
 These should be implemented as functions::
 
     def setUpModule():