Skip to content

gh-138307: Update the Ellipsis documentation #138306

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 18 commits into from
Sep 3, 2025
Merged

gh-138307: Update the Ellipsis documentation #138306

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
01a9007
Doc: Change Ellipsis doc at library/constants
adorilson Aug 31, 2025
e8e0582
Doc: Change Ellipsis doc at library/stdtypes
adorilson Aug 31, 2025
011ceb9
Doc: Add NumPy reference into Ellipsis doc at library/stdtypes
adorilson Aug 31, 2025
fae75b7
Doc: Add Ellipsis reference into the pass statement section at tutorial
adorilson Aug 31, 2025
5688029
Doc: Update Ellipsis doc concerns assignments at library/constants
adorilson Aug 31, 2025
f57a7d4
Update Doc/library/stdtypes.rst
adorilson Aug 31, 2025
bea09ee
Doc: Fix grammar on Ellipsis docs (library/constants.rst)
adorilson Sep 1, 2025
7cbfd39
Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst)
adorilson Sep 1, 2025
767dd95
Doc: Fix grammar on Ellipsis docs (library/stdtypes.rst)
adorilson Sep 1, 2025
66f0b96
Doc: Remove pretty printers reference from Ellipsis doc at library/st…
adorilson Sep 1, 2025
fd21e0a
Doc: Update index concerns Ellipsis object and pass statement
adorilson Sep 1, 2025
ce58d75
Doc: Improve Ellipsis doc at library/constants
adorilson Sep 1, 2025
929e89f
Doc: Improve Ellipsis doc at library/stdtypes
adorilson Sep 2, 2025
a0dfdd4
Doc: Change the "..." glossary entry to mention the Ellipsis object
adorilson Sep 2, 2025
57ae57e
Doc: Some improvements concern ellipsis into typing doc
adorilson Sep 2, 2025
9339d93
Minor update Doc/tutorial/controlflow.rst
adorilson Sep 2, 2025
28258f6
Update Doc/library/constants.rst
adorilson Sep 2, 2025
f08b81c
Update Doc/library/stdtypes.rst
adorilson Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions Doc/library/constants.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 as a
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.


Expand Down
15 changes: 14 additions & 1 deletion Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5869,13 +5869,26 @@ 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 <prettyprinter-objects>`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll fix it.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

:const:`documentation tests <doctest.ELLIPSIS>`,
Copy link
Member

@nedbat nedbat Sep 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

:ref:`type annotations <annotating-callables>`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

or instead of :ref:`pass statement <tut-pass>`.


.. seealso::

`NumPy's slicing and striding <https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding>`_
A well-known Ellipsis use in third party packages is for slicing in Numpy.


.. _bltin-notimplemented-object:

Expand Down
7 changes: 7 additions & 0 deletions Doc/tutorial/controlflow.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok.

Copy link
Member

@JelleZijlstra JelleZijlstra Sep 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

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

Expand Down
Loading