[pull] main from python:main

Doc/extending/extending.rst

@@ -426,7 +426,7 @@ A pointer to the module definition must be returned via :c:func:`PyModuleDef_Ini
 so that the import machinery can create the module and store it in ``sys.modules``.
 
 When embedding Python, the :c:func:`!PyInit_spam` function is not called
-automatically unless there's an entry in the :c:data:`PyImport_Inittab` table.
+automatically unless there's an entry in the :c:data:`!PyImport_Inittab` table.
 To add the module to the initialization table, use :c:func:`PyImport_AppendInittab`,
 optionally followed by an import of the module::
 

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/library/collections.abc.rst

@@ -272,9 +272,17 @@ Collections Abstract Base Classes -- Detailed Descriptions
    linked list), the mixins will have quadratic performance and will
    likely need to be overridden.
 
-   .. versionchanged:: 3.5
-      The index() method added support for *stop* and *start*
-      arguments.
+   .. method:: index(value, start=0, stop=None)
+
+      Return first index of *value*.
+
+      Raises :exc:`ValueError` if the value is not present.
+
+      Supporting the *start* and *stop* arguments is optional, but recommended.
+
+      .. versionchanged:: 3.5
+         The :meth:`!index` method added support for *stop* and *start*
+         arguments.
 
 .. class:: Set
            MutableSet

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/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/test.rst

@@ -851,7 +851,7 @@ The :mod:`test.support` module defines the following functions:
    Decorator for tests that fill the address space.
 
 
-.. function:: linked_with_musl()
+.. function:: linked_to_musl()
 
    Return ``False`` if there is no evidence the interpreter was compiled with
    ``musl``, otherwise return a version triple, either ``(0, 0, 0)`` if the

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():

Doc/reference/lexical_analysis.rst

@@ -1351,67 +1351,62 @@ Formally, imaginary literals are described by the following lexical definition:
    imagnumber: (`floatnumber` | `digitpart`) ("j" | "J")
 
 
-.. _operators:
-
-Operators
-=========
-
-.. index:: single: operators
-
-The following tokens are operators:
-
-.. code-block:: none
-
-
-   +       -       *       **      /       //      %      @
-   <<      >>      &       |       ^       ~       :=
-   <       >       <=      >=      ==      !=
-
-
 .. _delimiters:
-
-Delimiters
-==========
-
-.. index:: single: delimiters
-
-The following tokens serve as delimiters in the grammar:
-
-.. code-block:: none
-
-   (       )       [       ]       {       }
-   ,       :       !       .       ;       @       =
-
-The period can also occur in floating-point and imaginary literals.
-
+.. _operators:
 .. _lexical-ellipsis:
 
-A sequence of three periods has a special meaning as an
-:py:data:`Ellipsis` literal:
-
-.. code-block:: none
-
-   ...
-
-The following *augmented assignment operators* serve
-lexically as delimiters, but also perform an operation:
+Operators and delimiters
+========================
 
-.. code-block:: none
-
-   ->      +=      -=      *=      /=      //=     %=
-   @=      &=      |=      ^=      >>=     <<=     **=
-
-The following printing ASCII characters have special meaning as part of other
-tokens or are otherwise significant to the lexical analyzer:
-
-.. code-block:: none
-
-   '       "       #       \
+.. index::
+   single: operators
+   single: delimiters
 
-The following printing ASCII characters are not used in Python.  Their
-occurrence outside string literals and comments is an unconditional error:
+The following grammar defines :dfn:`operator` and :dfn:`delimiter` tokens,
+that is, the generic :data:`~token.OP` token type.
+A :ref:`list of these tokens and their names <token_operators_delimiters>`
+is also available in the :mod:`!token` module documentation.
 
-.. code-block:: none
+.. grammar-snippet::
+   :group: python-grammar
 
-   $       ?       `
+   OP:
+      | assignment_operator
+      | bitwise_operator
+      | comparison_operator
+      | enclosing_delimiter
+      | other_delimiter
+      | arithmetic_operator
+      | "..."
+      | other_op
+
+   assignment_operator:   "+=" | "-=" | "*=" | "**=" | "/="  | "//=" | "%=" |
+                          "&=" | "|=" | "^=" | "<<=" | ">>=" | "@="  | ":="
+   bitwise_operator:      "&"  | "|"  | "^"  | "~"   | "<<"  | ">>"
+   comparison_operator:   "<=" | ">=" | "<"  | ">"   | "=="  | "!="
+   enclosing_delimiter:   "("  | ")"  | "["  | "]"   | "{"   | "}"
+   other_delimiter:       ","  | ":"  | "!"  | ";"   | "="   | "->"
+   arithmetic_operator:   "+"  | "-"  | "**" | "*"   | "//"  | "/"   | "%"
+   other_op:              "."  | "@"
+
+.. note::
+
+   Generally, *operators* are used to combine :ref:`expressions <expressions>`,
+   while *delimiters* serve other purposes.
+   However, there is no clear, formal distinction between the two categories.
+
+   Some tokens can serve as either operators or delimiters, depending on usage.
+   For example, ``*`` is both the multiplication operator and a delimiter used
+   for sequence unpacking, and ``@`` is both the matrix multiplication and
+   a delimiter that introduces decorators.
+
+   For some tokens, the distinction is unclear.
+   For example, some people consider ``.``, ``(``, and ``)`` to be delimiters, while others
+   see the :py:func:`getattr` operator and the function call operator(s).
+
+   Some of Python's operators, like ``and``, ``or``, and ``not in``, use
+   :ref:`keyword <keywords>` tokens rather than "symbols" (operator tokens).
+
+A sequence of three consecutive periods (``...``) has a special
+meaning as an :py:data:`Ellipsis` literal.
 

Doc/reference/simple_stmts.rst

@@ -831,6 +831,9 @@ where the :keyword:`import` statement occurs.
 
 .. index:: single: __all__ (optional module attribute)
 
+.. attribute:: module.__all__
+   :no-typesetting:
+
 The *public names* defined by a module are determined by checking the module's
 namespace for a variable named ``__all__``; if defined, it must be a sequence
 of strings which are names defined or imported by that module.  The names

Doc/tools/.nitignore

@@ -11,7 +11,6 @@ Doc/c-api/module.rst
 Doc/c-api/stable.rst
 Doc/c-api/type.rst
 Doc/c-api/typeobj.rst
-Doc/extending/extending.rst
 Doc/library/ast.rst
 Doc/library/asyncio-extending.rst
 Doc/library/email.charset.rst
@@ -61,10 +60,4 @@ Doc/using/windows.rst
 Doc/whatsnew/2.4.rst
 Doc/whatsnew/2.5.rst
 Doc/whatsnew/2.6.rst
-Doc/whatsnew/2.7.rst
-Doc/whatsnew/3.3.rst
-Doc/whatsnew/3.4.rst
-Doc/whatsnew/3.5.rst
-Doc/whatsnew/3.6.rst
-Doc/whatsnew/3.8.rst
 Doc/whatsnew/3.10.rst

Doc/tutorial/controlflow.rst

@@ -251,6 +251,7 @@ statements: a ``try`` statement's ``else`` clause runs when no exception
 occurs, and a loop's ``else`` clause runs when no ``break`` occurs. For more on
 the ``try`` statement and exceptions, see :ref:`tut-handling`.
 
+.. index:: single: ...; ellipsis literal
 .. _tut-pass:
 
 :keyword:`!pass` Statements
@@ -277,6 +278,12 @@ at a more abstract level.  The :keyword:`!pass` is silently ignored::
    ...     pass   # Remember to implement this!
    ...
 
+For this last case, many people use the ellipsis literal :code:`...` instead of
+:code:`pass`. This use has no special meaning to Python, and is not part of
+the language definition (you could use any constant expression here), but
+:code:`...` is used conventionally as a placeholder body as well.
+See :ref:`bltin-ellipsis-object`.
+
 
 .. _tut-match: