Skip to content

Commit 929e89f

Browse files
committed
Doc: Improve Ellipsis doc at library/stdtypes
1 parent ce58d75 commit 929e89f

File tree

1 file changed

+20
-11
lines changed

1 file changed

+20
-11
lines changed

Doc/library/stdtypes.rst

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5869,25 +5869,34 @@ It is written as ``None``.
58695869
The Ellipsis Object
58705870
-------------------
58715871

5872-
This object is commonly used as a placeholder for other objects, values or even
5873-
instructions. It supports no
5874-
special operations. There is exactly one ellipsis object, named
5872+
This object is commonly used used to indicate that something is omitted.
5873+
It supports no special operations. There is exactly one ellipsis object, named
58755874
:const:`Ellipsis` (a built-in name). ``type(Ellipsis)()`` produces the
58765875
:const:`Ellipsis` singleton.
58775876

58785877
It is written as ``Ellipsis`` or ``...``.
58795878

5880-
For instance, in the standard library and its documentation, ``Ellipsis`` can
5881-
appears in
5882-
:const:`documentation tests <doctest.ELLIPSIS>`,
5883-
:ref:`type annotations <annotating-callables>`,
5884-
or instead of :ref:`pass statement <tut-pass>`.
5879+
In typical use, ``...`` as the ``Ellipsis`` object appears in a few different
5880+
places, for instance:
58855881

5882+
- In type annotations, such as :ref:`callable arguments <annotating-callables>`
5883+
or :ref:`tuple elements <annotating-tuples>`.
58865884

5887-
.. seealso::
5885+
- As the body of a function instead of a :ref:`pass statement <tut-pass>`.
5886+
5887+
- In third-party libraries, such as `Numpy's slicing and striding
5888+
<https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding>`_.
5889+
5890+
Python also uses three dots in ways that are not ``Ellipsis`` objects, for instance:
5891+
5892+
- Doctest's :const:`ELLIPSIS <doctest.ELLIPSIS>`, as a pattern for missing content.
5893+
5894+
- The default Python prompt of the :term:`interactive` shell when entering the
5895+
code for an indented code block, meaning "please finish your statement".
58885896

5889-
`NumPy's slicing and striding <https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding>`_
5890-
A well-known Ellipsis use in third party packages is for slicing in Numpy.
5897+
Lastly, the Python documentation often uses three dots in conventional English
5898+
usage to mean omitted content, even in code examples that also use them as the
5899+
``Ellipsis``.
58915900

58925901

58935902
.. _bltin-notimplemented-object:

0 commit comments

Comments
 (0)