https://github.com/python/cpython/commit/4e25f012e746f478738588f35686bcc8dd6f96a4
commit: 4e25f012e746f478738588f35686bcc8dd6f96a4
branch: 3.13
author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com>
committer: JelleZijlstra <jelle.zijls...@gmail.com>
date: 2025-09-05T13:47:19-07:00
summary:
[3.13] gh-138307: Update the Ellipsis documentation (GH-138306) (#138439)
(cherry picked from commit 88665de120d7f89e18774b136f3c898bcfe52c7b)
Co-authored-by: Adorilson Bezerra <adoril...@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+stanfromirel...@users.noreply.github.com>
Co-authored-by: Éric <mer...@netwok.org>
Co-authored-by: Ned Batchelder <n...@nedbatchelder.com>
files:
M Doc/glossary.rst
M Doc/library/constants.rst
M Doc/library/stdtypes.rst
M Doc/library/typing.rst
M Doc/tutorial/controlflow.rst
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index ea62fccdc3d265..db8a4fc45a1a5d 100644
--- 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/constants.rst b/Doc/library/constants.rst
index dddd26c5b838c5..7d17eb8a62ac77 100644
--- a/Doc/library/constants.rst
+++ b/Doc/library/constants.rst
@@ -62,8 +62,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/stdtypes.rst b/Doc/library/stdtypes.rst
index 7c81e77f5b21e9..45ac0406a03aaa 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -5670,13 +5670,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/typing.rst b/Doc/library/typing.rst
index b9277decbdba42..30d6322efa2d4f 100644
--- 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, ...]``::
@@ -1154,6 +1159,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/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 436adb56863cd4..73f33d42139eda 100644
--- 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:
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: arch...@mail-archive.com
