From 01a9007117a85e6232e46d2f01f56d8ea0489b6a Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Sun, 31 Aug 2025 16:35:23 +0100 Subject: [PATCH 01/18] Doc: Change Ellipsis doc at library/constants --- Doc/library/constants.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 04080fd0d865ec..7064e5b2c5bac2 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -65,8 +65,8 @@ 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 as a + placeholder of another values. ``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type. From e8e058223a407c309df0d1764abdbf11e56a2b6e Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Sun, 31 Aug 2025 18:22:32 +0100 Subject: [PATCH 02/18] Doc: Change Ellipsis doc at library/stdtypes --- Doc/library/stdtypes.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 3320f7c3bba728..dcd50a101acc6a 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5869,13 +5869,20 @@ It is written as ``None``. The Ellipsis Object ------------------- -This object is commonly used by slicing (see :ref:`slicings`). It supports no +This object is commonly used as a placeholder of another objects, values or even +instructions. 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 ``...``. +For instance, at the standard library and its documentation, ``Ellipsis`` can +appears in :ref:`pretty printers `, +:const:`documentation tests `, +:ref:`type annotations `, +or instead of :ref:`pass statement `. + .. _bltin-notimplemented-object: From 011ceb98c9ba8b0075e2d1a3f3fa91effeab1d3e Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Sun, 31 Aug 2025 18:43:49 +0100 Subject: [PATCH 03/18] Doc: Add NumPy reference into Ellipsis doc at library/stdtypes --- Doc/library/stdtypes.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index dcd50a101acc6a..3cdb9948313eab 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5884,6 +5884,12 @@ appears in :ref:`pretty printers `, or instead of :ref:`pass statement `. +.. seealso:: + + `NumPy's slicing and striding `_ + A known-well Ellipsis use on third packages is the slicing on the Numpy. + + .. _bltin-notimplemented-object: The NotImplemented Object From fae75b7bdcfad3580ddbe1b5dae0258f046898c7 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Sun, 31 Aug 2025 19:44:37 +0100 Subject: [PATCH 04/18] Doc: Add Ellipsis reference into the pass statement section at tutorial --- Doc/tutorial/controlflow.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 5c0e8f34bf82f4..29d355995cf776 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: ...; placeholder .. _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 it 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: From 5688029d8b5642783b96099c1581335b91b256cd Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Sun, 31 Aug 2025 20:24:12 +0100 Subject: [PATCH 05/18] Doc: Update Ellipsis doc concerns assignments at library/constants --- Doc/library/constants.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 7064e5b2c5bac2..8c458d1a9cac03 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -66,7 +66,8 @@ A small number of constants live in the built-in namespace. They are: .. data:: Ellipsis The same as the ellipsis literal "``...``", an object frequently used as a - placeholder of another values. + placeholder of another values. Assignments to ``Ellipsis`` are possible. + However, assignments to ``...`` are illegal and raise a :exc:`SyntaxError`. ``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type. From f57a7d43f8cb990bf55b427c8b90a1e072575ada Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Sun, 31 Aug 2025 22:40:20 +0100 Subject: [PATCH 06/18] Update Doc/library/stdtypes.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/stdtypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 3cdb9948313eab..5ebe2ca84a2910 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5887,7 +5887,7 @@ or instead of :ref:`pass statement `. .. seealso:: `NumPy's slicing and striding `_ - A known-well Ellipsis use on third packages is the slicing on the Numpy. + A well-known Ellipsis use in third party packages is for slicing in Numpy. .. _bltin-notimplemented-object: From bea09ee6b61823ffd53b6b02862ea372202e44f1 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Mon, 1 Sep 2025 09:59:52 +0100 Subject: [PATCH 07/18] Doc: Fix grammar on Ellipsis docs (library/constants.rst) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Éric --- Doc/library/constants.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 8c458d1a9cac03..5cea65f853c1f3 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -66,8 +66,8 @@ A small number of constants live in the built-in namespace. They are: .. data:: Ellipsis The same as the ellipsis literal "``...``", an object frequently used as a - placeholder of another values. Assignments to ``Ellipsis`` are possible. - However, assignments to ``...`` are illegal and raise a :exc:`SyntaxError`. + placeholder for another value. Assignment to ``Ellipsis`` is possible, but + assignment to ``...`` is not possible and raises a :exc:`SyntaxError`. ``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type. From 7cbfd39e3e9daf7890466f637a0bbd21fcd2d84e Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Mon, 1 Sep 2025 10:00:31 +0100 Subject: [PATCH 08/18] Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Éric --- Doc/library/stdtypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 5ebe2ca84a2910..aaf59c479e4a97 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5877,7 +5877,7 @@ special operations. There is exactly one ellipsis object, named It is written as ``Ellipsis`` or ``...``. -For instance, at the standard library and its documentation, ``Ellipsis`` can +For instance, in the standard library and its documentation, ``Ellipsis`` can appears in :ref:`pretty printers `, :const:`documentation tests `, :ref:`type annotations `, From 767dd953bcda8093a70571dd949eda0b06d8dfb9 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Mon, 1 Sep 2025 10:01:22 +0100 Subject: [PATCH 09/18] Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Éric --- Doc/library/stdtypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index aaf59c479e4a97..dd96bb3bbefb6f 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5869,7 +5869,7 @@ It is written as ``None``. The Ellipsis Object ------------------- -This object is commonly used as a placeholder of another objects, values or even +This object is commonly used as a placeholder for other objects, values or even instructions. It supports no special operations. There is exactly one ellipsis object, named :const:`Ellipsis` (a built-in name). ``type(Ellipsis)()`` produces the From 66f0b968c943caed760199ffba8322e1a2f1b667 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Mon, 1 Sep 2025 10:39:47 +0100 Subject: [PATCH 10/18] Doc: Remove pretty printers reference from Ellipsis doc at library/stdtypes --- Doc/library/stdtypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index dd96bb3bbefb6f..e38b88bd07a2d1 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5878,7 +5878,7 @@ special operations. There is exactly one ellipsis object, named It is written as ``Ellipsis`` or ``...``. For instance, in the standard library and its documentation, ``Ellipsis`` can -appears in :ref:`pretty printers `, +appears in :const:`documentation tests `, :ref:`type annotations `, or instead of :ref:`pass statement `. From fd21e0a1215a8c8ef9d94d7d3b9324fe406ea7aa Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Mon, 1 Sep 2025 10:52:53 +0100 Subject: [PATCH 11/18] Doc: Update index concerns Ellipsis object and pass statement --- Doc/tutorial/controlflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 29d355995cf776..424d699c8c7952 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -251,7 +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: ...; placeholder +.. index:: single: ...; ellipsis literal .. _tut-pass: :keyword:`!pass` Statements From ce58d75cc6b2fdf930a07f6e220d445f20fc19a4 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Mon, 1 Sep 2025 18:10:41 +0100 Subject: [PATCH 12/18] Doc: Improve Ellipsis doc at library/constants --- Doc/library/constants.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 5cea65f853c1f3..7ec5c2d1df7d24 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -65,8 +65,8 @@ 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 "``...``", an object frequently used as a - placeholder for another value. Assignment to ``Ellipsis`` is possible, but + The same as the ellipsis literal "``...``", an object frequently used to + indicate that something is omitted. Assignment to ``Ellipsis`` is possible, but assignment to ``...`` is not possible and raises a :exc:`SyntaxError`. ``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type. From 929e89f5dc0403bb0e97e450c0b26d3fee454c2b Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Tue, 2 Sep 2025 09:49:42 +0100 Subject: [PATCH 13/18] Doc: Improve Ellipsis doc at library/stdtypes --- Doc/library/stdtypes.rst | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index e38b88bd07a2d1..401964be22a500 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5869,25 +5869,34 @@ It is written as ``None``. The Ellipsis Object ------------------- -This object is commonly used as a placeholder for other objects, values or even -instructions. 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 ``...``. -For instance, in the standard library and its documentation, ``Ellipsis`` can -appears in -:const:`documentation tests `, -:ref:`type annotations `, -or instead of :ref:`pass statement `. +In typical use, ``...`` as the ``Ellipsis`` object appears in a few different +places, for instance: +- In type annotations, such as :ref:`callable arguments ` + or :ref:`tuple elements `. -.. seealso:: +- As the body of a function instead of a :ref:`pass statement `. + +- In third-party libraries, such as `Numpy's slicing and striding + `_. + +Python also uses three dots in ways that are not ``Ellipsis`` objects, for instance: + +- Doctest's :const:`ELLIPSIS `, as a pattern for missing content. + +- The default Python prompt of the :term:`interactive` shell when entering the + code for an indented code block, meaning "please finish your statement". - `NumPy's slicing and striding `_ - A well-known Ellipsis use in third party packages is for slicing in Numpy. +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: From a0dfdd4e8e8af5dd6fa4def65bba10c9e2e29a78 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Tue, 2 Sep 2025 10:03:44 +0100 Subject: [PATCH 14/18] Doc: Change the "..." glossary entry to mention the Ellipsis object --- Doc/glossary.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 453445211672da..d0fd05cdbdfabe 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 ` object. abstract base class Abstract base classes complement :term:`duck-typing` by From 57ae57eced60c40f7120022f37ad2647c3c8b0ee Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Tue, 2 Sep 2025 10:45:36 +0100 Subject: [PATCH 15/18] Doc: Some improvements concern ellipsis into typing doc --- Doc/library/typing.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 9dbac8ce75d489..c8eb1d08a1bb2a 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, ...]``:: @@ -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 ` and :class:`ParamSpec` to annotate a higher-order callable which adds, removes, or transforms parameters of another From 9339d93507bf81c2ab4ace87103455fb418b49bf Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Tue, 2 Sep 2025 15:05:32 +0100 Subject: [PATCH 16/18] Minor update Doc/tutorial/controlflow.rst Co-authored-by: Ned Batchelder --- Doc/tutorial/controlflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 424d699c8c7952..6d4928f211a69d 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -279,7 +279,7 @@ at a more abstract level. The :keyword:`!pass` is silently ignored:: ... For this last case, many people use the ellipsis literal :code:`...` instead of -:code:`pass`. This use has no special meaning to Python, and it is not part 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`. From 28258f6c817ed64f40d2a19ea363deb4182896f1 Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Tue, 2 Sep 2025 15:05:56 +0100 Subject: [PATCH 17/18] Update Doc/library/constants.rst Co-authored-by: Ned Batchelder --- Doc/library/constants.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 7ec5c2d1df7d24..d058ba206c6cd6 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -67,7 +67,7 @@ A small number of constants live in the built-in namespace. They are: The same as the ellipsis literal "``...``", an object frequently used to indicate that something is omitted. Assignment to ``Ellipsis`` is possible, but - assignment to ``...`` is not possible and raises a :exc:`SyntaxError`. + assignment to ``...`` raises a :exc:`SyntaxError`. ``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type. From f08b81c8d127158383cc913a53c2921b6264c64c Mon Sep 17 00:00:00 2001 From: Adorilson Bezerra Date: Tue, 2 Sep 2025 15:06:23 +0100 Subject: [PATCH 18/18] Update Doc/library/stdtypes.rst Co-authored-by: Ned Batchelder --- Doc/library/stdtypes.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 401964be22a500..5bc8257c37b89b 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5891,8 +5891,7 @@ Python also uses three dots in ways that are not ``Ellipsis`` objects, for insta - Doctest's :const:`ELLIPSIS `, as a pattern for missing content. -- The default Python prompt of the :term:`interactive` shell when entering the - code for an indented code block, meaning "please finish your statement". +- 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