tj-python · pull · Sep 3, 2025 · Sep 3, 2025 · Sep 3, 2025 · Sep 3, 2025
diff --git a/Doc/extending/extending.rst b/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::
 

diff --git a/Doc/glossary.rst b/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

diff --git a/Doc/library/collections.abc.rst b/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

diff --git a/Doc/library/constants.rst b/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.
 
 

diff --git a/Doc/library/shutil.rst b/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`

diff --git a/Doc/library/stdtypes.rst b/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:
 

diff --git a/Doc/library/test.rst b/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

diff --git a/Doc/library/typing.rst b/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

diff --git a/Doc/reference/lexical_analysis.rst b/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.
 
diff --git a/Doc/reference/simple_stmts.rst b/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

diff --git a/Doc/tools/.nitignore b/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
@@ -57,12 +56,7 @@ Doc/library/xmlrpc.server.rst
 Doc/library/zlib.rst
 Doc/reference/compound_stmts.rst
 Doc/reference/datamodel.rst
-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.4.rst
-Doc/whatsnew/3.5.rst
-Doc/whatsnew/3.6.rst
 Doc/whatsnew/3.10.rst
diff --git a/Doc/tutorial/controlflow.rst b/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:
 

diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
@@ -398,7 +398,7 @@ customization.
      - Description
 
    * - ``default_tag``
-     - ``PYTHON_MANAGER_DEFAULT``
+     - .. envvar:: PYTHON_MANAGER_DEFAULT
      - The preferred default version to launch or install.
        By default, this is interpreted as the most recent non-prerelease version
        from the CPython team.
@@ -812,7 +812,7 @@ default).
        ``python.exe`` alias is set to "Python (default)"
 
    * - ``python`` and ``py`` don't launch the runtime I expect
-     - Check your ``PYTHON_MANAGER_DEFAULT`` environment variable
+     - Check your :envvar:`PYTHON_MANAGER_DEFAULT` environment variable
        or ``default_tag`` configuration.
        The ``py list`` command will show your default based on these settings.
 
@@ -1802,7 +1802,7 @@ program, which performs a :envvar:`PATH` search.
 If an executable matching the first argument after the ``env`` command cannot
 be found, but the argument starts with ``python``, it will be handled as
 described for the other virtual commands.
-The environment variable :envvar:`PYLAUNCHER_NO_SEARCH_PATH` may be set
+The environment variable :envvar:`!PYLAUNCHER_NO_SEARCH_PATH` may be set
 (to any value) to skip this search of :envvar:`PATH`.
 
 Shebang lines that do not match any of these patterns are looked up in the
@@ -1869,7 +1869,7 @@ For example, a shebang line of ``#!python`` has no version qualifier, while
 ``#!python3`` has a version qualifier which specifies only a major version.
 
 If no version qualifiers are found in a command, the environment
-variable :envvar:`PY_PYTHON` can be set to specify the default version
+variable :envvar:`!PY_PYTHON` can be set to specify the default version
 qualifier. If it is not set, the default is "3". The variable can
 specify any value that may be passed on the command line, such as "3",
 "3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only
@@ -1942,7 +1942,7 @@ For example:
 Diagnostics
 -----------
 
-If an environment variable :envvar:`PYLAUNCHER_DEBUG` is set (to any value), the
+If an environment variable :envvar:`!PYLAUNCHER_DEBUG` is set (to any value), the
 launcher will print diagnostic information to stderr (i.e. to the console).
 While this information manages to be simultaneously verbose *and* terse, it
 should allow you to see what versions of Python were located, why a
@@ -1952,7 +1952,7 @@ target Python. It is primarily intended for testing and debugging.
 Dry Run
 -------
 
-If an environment variable :envvar:`PYLAUNCHER_DRYRUN` is set (to any value),
+If an environment variable :envvar:`!PYLAUNCHER_DRYRUN` is set (to any value),
 the launcher will output the command it would have run, but will not actually
 launch Python. This may be useful for tools that want to use the launcher to
 detect and then launch Python directly. Note that the command written to
@@ -1962,14 +1962,14 @@ the console.
 Install on demand
 -----------------
 
-If an environment variable :envvar:`PYLAUNCHER_ALLOW_INSTALL` is set (to any
+If an environment variable :envvar:`!PYLAUNCHER_ALLOW_INSTALL` is set (to any
 value), and the requested Python version is not installed but is available on
 the Microsoft Store, the launcher will attempt to install it. This may require
 user interaction to complete, and you may need to run the command again.
 
-An additional :envvar:`PYLAUNCHER_ALWAYS_INSTALL` variable causes the launcher
+An additional :envvar:`!PYLAUNCHER_ALWAYS_INSTALL` variable causes the launcher
 to always try to install Python, even if it is detected. This is mainly intended
-for testing (and should be used with :envvar:`PYLAUNCHER_DRYRUN`).
+for testing (and should be used with :envvar:`!PYLAUNCHER_DRYRUN`).
 
 Return codes
 ------------