gh-138307: Update the Ellipsis documentation #138306

adorilson · 2025-08-31T19:34:07Z

After a discuss thread, this PR updates the Ellipsis documentation.

📚 Documentation preview 📚: https://cpython-previews--138306.org.readthedocs.build/

Issue: Ellipsis documentation #138307

Doc/library/stdtypes.rst

nedbat · 2025-08-31T21:22:47Z

Doc/library/stdtypes.rst

 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 <prettyprinter-objects>`,


This gets awkward: the use in pretty printing is three dots, but it's not an Ellipsis object. It's a typographic convention for omitted content (which is why Python uses three dots for this).

I'll fix it.

Do you think we should add this third type to the glossary?

Likewise recursive_repr uses ... but it's not the Ellipsis form of ....

What about doctest.ELLIPIS? Now, I'm thinking it is three dots, not the Ellipsis object.

Co-authored-by: Stan Ulbrych <[email protected]>

Doc/library/constants.rst

Doc/library/stdtypes.rst

Co-authored-by: Éric <[email protected]>

…dtypes

nedbat · 2025-09-01T11:50:13Z

Doc/library/stdtypes.rst

 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 <doctest.ELLIPSIS>`,


doctest.ELLIPSIS is not an Ellipsis object. It's yet another instance of using three dots to mean "something is missing here." In a doctest, ... matches any text, like .* in a regex.

BTW, another use of three dots is the secondary REPL prompt:

>>> ( ...

We can list out these "faux Ellipses" (not in those words) as a way of helping people who end up here because they were trying to figure out what something means.

I would structure it something like this:

In typical use, ``...`` as an Ellipsis appears in a few different places: - In type annotations for :ref:`Callable arguments <annotating-callables>` or `tuple elements <find-the-reference>` - 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: - Doctest's :const:`doctest.ELLIPSIS`, as a pattern for missing content - As the interactive prompt for "please finish your statement" 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 an Ellipsis.

JelleZijlstra · 2025-09-01T14:09:44Z

Doc/library/constants.rst

+   The same as the ellipsis literal "``...``", an object frequently used as a
+   placeholder for another value. Assignment to  ``Ellipsis`` is possible, but


I'm not sure "a placeholder for another value" is a good summary. I don't think it describes many of the typing use cases, for one.

Maybe "to indicate that something is omitted"?

JelleZijlstra · 2025-09-01T14:11:52Z

Doc/library/stdtypes.rst

+For instance, in the standard library and its documentation, ``Ellipsis`` can
+appears in
+:const:`documentation tests <doctest.ELLIPSIS>`,
+:ref:`type annotations <annotating-callables>`,


The link goes to callables (Callable[..., T] meaning a gradual type covering callables with any sets of arguments), but this is not the only use in typing. It's also used for variable-length tuples (tuple[int, ...]), to represent an omitted default value in stubs or overloads (def f(x: int = ...) -> None:), and as an empty body for a function in stubs and a few other contexts (def f(x: int) -> None: ...).

I definitely don't have the right links, i wanted to get the language right first.

adorilson · 2025-09-02T09:54:00Z

@nedbat @JelleZijlstra

The latest commits address your latest comments.
Beside, I changed the ... glossary entry to mention Ellipsis object instead of the constant one.
I think It's more useful now.

Thank you for the comments and suggestions.

nedbat · 2025-09-02T11:39:24Z

Doc/tutorial/controlflow.rst

@@ -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


Suggested change

For this last case, many people use the ellipsis literal :code:`...` instead of

For this last case, many people use the Ellipsis literal :code:`...` instead of

Here, I think it is lowercase. Because it is the ellipsis mark, not the object one. Like here: https://docs.python.org/3.13/library/constants.html#Ellipsis

I don't think so, it does evaluate to the Ellipsis singleton, even if that value is not used.

>>> ast.parse('def f(): ...').body[0].body[0].value Constant(value=Ellipsis, kind=None)

Doc/tutorial/controlflow.rst

Doc/library/constants.rst

Doc/library/stdtypes.rst

nedbat

A few small tweaks and it's ready to go.

Co-authored-by: Ned Batchelder <[email protected]>

miss-islington-app · 2025-09-03T11:28:08Z

Thanks @adorilson for the PR, and @nedbat for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

miss-islington-app · 2025-09-03T11:28:08Z

Thanks @adorilson for the PR, and @nedbat for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

* Doc: Change Ellipsis doc at library/constants * Doc: Change Ellipsis doc at library/stdtypes * Doc: Add NumPy reference into Ellipsis doc at library/stdtypes * Doc: Add Ellipsis reference into the pass statement section at tutorial * Doc: Update Ellipsis doc concerns assignments at library/constants * Update Doc/library/stdtypes.rst Co-authored-by: Stan Ulbrych <[email protected]> * Doc: Fix grammar on Ellipsis docs (library/constants.rst) Co-authored-by: Éric <[email protected]> * Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst) Co-authored-by: Éric <[email protected]> * Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst) Co-authored-by: Éric <[email protected]> * Doc: Remove pretty printers reference from Ellipsis doc at library/stdtypes * Doc: Update index concerns Ellipsis object and pass statement * Doc: Improve Ellipsis doc at library/constants * Doc: Improve Ellipsis doc at library/stdtypes * Doc: Change the "..." glossary entry to mention the Ellipsis object * Doc: Some improvements concern ellipsis into typing doc * Minor update Doc/tutorial/controlflow.rst Co-authored-by: Ned Batchelder <[email protected]> * Update Doc/library/constants.rst Co-authored-by: Ned Batchelder <[email protected]> * Update Doc/library/stdtypes.rst Co-authored-by: Ned Batchelder <[email protected]> --------- (cherry picked from commit 88665de) Co-authored-by: Adorilson Bezerra <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Éric <[email protected]> Co-authored-by: Ned Batchelder <[email protected]>

bedevere-app · 2025-09-03T11:28:21Z

GH-138439 is a backport of this pull request to the 3.13 branch.

bedevere-app · 2025-09-03T11:28:25Z

GH-138440 is a backport of this pull request to the 3.14 branch.

) (cherry picked from commit 88665de) Co-authored-by: Adorilson Bezerra <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Éric <[email protected]> Co-authored-by: Ned Batchelder <[email protected]>

* Doc: Change Ellipsis doc at library/constants * Doc: Change Ellipsis doc at library/stdtypes * Doc: Add NumPy reference into Ellipsis doc at library/stdtypes * Doc: Add Ellipsis reference into the pass statement section at tutorial * Doc: Update Ellipsis doc concerns assignments at library/constants * Update Doc/library/stdtypes.rst Co-authored-by: Stan Ulbrych <[email protected]> * Doc: Fix grammar on Ellipsis docs (library/constants.rst) Co-authored-by: Éric <[email protected]> * Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst) Co-authored-by: Éric <[email protected]> * Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst) Co-authored-by: Éric <[email protected]> * Doc: Remove pretty printers reference from Ellipsis doc at library/stdtypes * Doc: Update index concerns Ellipsis object and pass statement * Doc: Improve Ellipsis doc at library/constants * Doc: Improve Ellipsis doc at library/stdtypes * Doc: Change the "..." glossary entry to mention the Ellipsis object * Doc: Some improvements concern ellipsis into typing doc * Minor update Doc/tutorial/controlflow.rst Co-authored-by: Ned Batchelder <[email protected]> * Update Doc/library/constants.rst Co-authored-by: Ned Batchelder <[email protected]> * Update Doc/library/stdtypes.rst Co-authored-by: Ned Batchelder <[email protected]> --------- Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Éric <[email protected]> Co-authored-by: Ned Batchelder <[email protected]>

adorilson added 5 commits August 31, 2025 16:35

Doc: Change Ellipsis doc at library/constants

01a9007

Doc: Change Ellipsis doc at library/stdtypes

e8e0582

Doc: Add NumPy reference into Ellipsis doc at library/stdtypes

011ceb9

Doc: Add Ellipsis reference into the pass statement section at tutorial

fae75b7

Doc: Update Ellipsis doc concerns assignments at library/constants

5688029

bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Aug 31, 2025

github-project-automation bot added this to Docs PRs Aug 31, 2025

github-project-automation bot moved this to Todo in Docs PRs Aug 31, 2025

This comment was marked as resolved.

Sign in to view

adorilson mentioned this pull request Aug 31, 2025

Ellipsis documentation #138307

Open

picnixz changed the title ~~Doc: Update the Ellipsis documentation~~ gh-138307: Update the Ellipsis documentation Aug 31, 2025

StanFromIreland reviewed Aug 31, 2025

View reviewed changes

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

nedbat reviewed Aug 31, 2025

View reviewed changes

Update Doc/library/stdtypes.rst

f57a7d4

Co-authored-by: Stan Ulbrych <[email protected]>

merwok reviewed Sep 1, 2025

View reviewed changes

Doc/library/constants.rst Outdated Show resolved Hide resolved

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

adorilson and others added 5 commits September 1, 2025 09:59

Doc: Fix grammar on Ellipsis docs (library/constants.rst)

bea09ee

Co-authored-by: Éric <[email protected]>

Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst)

7cbfd39

Co-authored-by: Éric <[email protected]>

Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst)

767dd95

Co-authored-by: Éric <[email protected]>

Doc: Remove pretty printers reference from Ellipsis doc at library/st…

66f0b96

…dtypes

Doc: Update index concerns Ellipsis object and pass statement

fd21e0a

adorilson requested review from nedbat, AA-Turner, StanFromIreland and merwok September 1, 2025 09:59

nedbat reviewed Sep 1, 2025

View reviewed changes

JelleZijlstra reviewed Sep 1, 2025

View reviewed changes

Doc: Improve Ellipsis doc at library/constants

ce58d75

Doc: Some improvements concern ellipsis into typing doc

57ae57e

adorilson requested a review from AlexWaygood as a code owner September 2, 2025 09:50

adorilson requested review from nedbat and JelleZijlstra September 2, 2025 09:54

nedbat reviewed Sep 2, 2025

View reviewed changes

Doc/tutorial/controlflow.rst Outdated Show resolved Hide resolved

nedbat reviewed Sep 2, 2025

View reviewed changes

Doc/library/constants.rst Outdated Show resolved Hide resolved

nedbat reviewed Sep 2, 2025

View reviewed changes

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

nedbat approved these changes Sep 2, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels Sep 2, 2025

adorilson and others added 3 commits September 2, 2025 15:05

Minor update Doc/tutorial/controlflow.rst

9339d93

Co-authored-by: Ned Batchelder <[email protected]>

Update Doc/library/constants.rst

28258f6

Co-authored-by: Ned Batchelder <[email protected]>

Update Doc/library/stdtypes.rst

f08b81c

Co-authored-by: Ned Batchelder <[email protected]>

nedbat merged commit 88665de into python:main Sep 3, 2025
27 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Sep 3, 2025

bedevere-app bot removed the awaiting merge label Sep 3, 2025

nedbat added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Sep 3, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Sep 3, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Sep 3, 2025

		The same as the ellipsis literal "``...``", an object frequently used as a
		placeholder for another value. Assignment to ``Ellipsis`` is possible, but

	For this last case, many people use the ellipsis literal :code:`...` instead of
	For this last case, many people use the Ellipsis literal :code:`...` instead of

Uh oh!

gh-138307: Update the Ellipsis documentation #138306

gh-138307: Update the Ellipsis documentation #138306

Uh oh!

Conversation

adorilson commented Aug 31, 2025 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nedbat Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adorilson commented Sep 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nedbat left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app bot commented Sep 3, 2025

Uh oh!

miss-islington-app bot commented Sep 3, 2025

Uh oh!

bedevere-app bot commented Sep 3, 2025

Uh oh!

bedevere-app bot commented Sep 3, 2025

Uh oh!

Uh oh!

adorilson commented Aug 31, 2025 •

edited by bedevere-app bot

Loading

nedbat Sep 1, 2025 •

edited

Loading

JelleZijlstra Sep 2, 2025 •

edited

Loading