Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 4e25f01

Browse files
miss-islingtonadorilsonStanFromIrelandmerwoknedbat
authored
[3.13] gh-138307: Update the Ellipsis documentation (GH-138306) (#138439)
(cherry picked from commit 88665de) Co-authored-by: Adorilson Bezerra <adorilson@gmail.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
1 parent 509ea39 commit 4e25f01

File tree

5 files changed

+45
-7
lines changed

5 files changed

+45
-7
lines changed

‎Doc/glossary.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@ Glossary
2121
right delimiters (parentheses, square brackets, curly braces or triple
2222
quotes), or after specifying a decorator.
2323

24-
* The :const:`Ellipsis` built-in constant.
24+
.. index:: single: ...; ellipsis literal
25+
26+
* The three dots form of the :ref:`Ellipsis <bltin-ellipsis-object>` object.
2527

2628
abstract base class
2729
Abstract base classes complement :term:`duck-typing` by

‎Doc/library/constants.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,9 @@ A small number of constants live in the built-in namespace. They are:
6262
.. index:: single: ...; ellipsis literal
6363
.. data:: Ellipsis
6464

65-
The same as the ellipsis literal "``...``". Special value used mostly in conjunction
66-
with extended slicing syntax for user-defined container data types.
65+
The same as the ellipsis literal "``...``", an object frequently used to
66+
indicate that something is omitted. Assignment to ``Ellipsis`` is possible, but
67+
assignment to ``...`` raises a :exc:`SyntaxError`.
6768
``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type.
6869

6970

‎Doc/library/stdtypes.rst

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5670,13 +5670,34 @@ It is written as ``None``.
56705670
The Ellipsis Object
56715671
-------------------
56725672

5673-
This object is commonly used by slicing (see :ref:`slicings`). It supports no
5674-
special operations. There is exactly one ellipsis object, named
5673+
This object is commonly used used to indicate that something is omitted.
5674+
It supports no special operations. There is exactly one ellipsis object, named
56755675
:const:`Ellipsis` (a built-in name). ``type(Ellipsis)()`` produces the
56765676
:const:`Ellipsis` singleton.
56775677

56785678
It is written as ``Ellipsis`` or ``...``.
56795679

5680+
In typical use, ``...`` as the ``Ellipsis`` object appears in a few different
5681+
places, for instance:
5682+
5683+
- In type annotations, such as :ref:`callable arguments <annotating-callables>`
5684+
or :ref:`tuple elements <annotating-tuples>`.
5685+
5686+
- As the body of a function instead of a :ref:`pass statement <tut-pass>`.
5687+
5688+
- In third-party libraries, such as `Numpy's slicing and striding
5689+
<https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding>`_.
5690+
5691+
Python also uses three dots in ways that are not ``Ellipsis`` objects, for instance:
5692+
5693+
- Doctest's :const:`ELLIPSIS <doctest.ELLIPSIS>`, as a pattern for missing content.
5694+
5695+
- The default Python prompt of the :term:`interactive` shell when partial input is incomplete.
5696+
5697+
Lastly, the Python documentation often uses three dots in conventional English
5698+
usage to mean omitted content, even in code examples that also use them as the
5699+
``Ellipsis``.
5700+
56805701

56815702
.. _bltin-notimplemented-object:
56825703

‎Doc/library/typing.rst

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -230,9 +230,11 @@ For example:
230230

231231
callback: Callable[[str], Awaitable[None]] = on_update
232232

233+
.. index:: single: ...; ellipsis literal
234+
233235
The subscription syntax must always be used with exactly two values: the
234236
argument list and the return type. The argument list must be a list of types,
235-
a :class:`ParamSpec`, :data:`Concatenate`, or an ellipsis. The return type must
237+
a :class:`ParamSpec`, :data:`Concatenate`, or an ellipsis (``...``). The return type must
236238
be a single type.
237239

238240
If a literal ellipsis ``...`` is given as the argument list, it indicates that
@@ -375,8 +377,11 @@ accepts *any number* of type arguments::
375377
# but ``z`` has been assigned to a tuple of length 3
376378
z: tuple[int] = (1, 2, 3)
377379

380+
.. index:: single: ...; ellipsis literal
381+
378382
To denote a tuple which could be of *any* length, and in which all elements are
379-
of the same type ``T``, use ``tuple[T, ...]``. To denote an empty tuple, use
383+
of the same type ``T``, use the literal ellipsis ``...``: ``tuple[T, ...]``.
384+
To denote an empty tuple, use
380385
``tuple[()]``. Using plain ``tuple`` as an annotation is equivalent to using
381386
``tuple[Any, ...]``::
382387

@@ -1154,6 +1159,8 @@ These can be used as types in annotations. They all support subscription using
11541159

11551160
Special form for annotating higher-order functions.
11561161

1162+
.. index:: single: ...; ellipsis literal
1163+
11571164
``Concatenate`` can be used in conjunction with :ref:`Callable <annotating-callables>` and
11581165
:class:`ParamSpec` to annotate a higher-order callable which adds, removes,
11591166
or transforms parameters of another

‎Doc/tutorial/controlflow.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,7 @@ statements: a ``try`` statement's ``else`` clause runs when no exception
251251
occurs, and a loop's ``else`` clause runs when no ``break`` occurs. For more on
252252
the ``try`` statement and exceptions, see :ref:`tut-handling`.
253253

254+
.. index:: single: ...; ellipsis literal
254255
.. _tut-pass:
255256

256257
:keyword:`!pass` Statements
@@ -277,6 +278,12 @@ at a more abstract level. The :keyword:`!pass` is silently ignored::
277278
... pass # Remember to implement this!
278279
...
279280

281+
For this last case, many people use the ellipsis literal :code:`...` instead of
282+
:code:`pass`. This use has no special meaning to Python, and is not part of
283+
the language definition (you could use any constant expression here), but
284+
:code:`...` is used conventionally as a placeholder body as well.
285+
See :ref:`bltin-ellipsis-object`.
286+
280287

281288
.. _tut-match:
282289

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /