[3.13] gh-138307: Update the Ellipsis documentation (GH-138306) #138439

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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 <bltin-ellipsis-object>` object.

		abstract base class
		Abstract base classes complement :term:`duck-typing` by
Expand Down

5 changes: 3 additions & 2 deletions Doc/library/constants.rst

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -62,8 +62,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 to
	indicate that something is omitted. Assignment to ``Ellipsis`` is possible, but
	assignment to ``...`` raises a :exc:`SyntaxError`.
		``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type.


Expand Down

25 changes: 23 additions & 2 deletions Doc/library/stdtypes.rst

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -5670,13 +5670,34 @@ It is written as ``None``.
		The Ellipsis Object
		-------------------

	This object is commonly used by slicing (see :ref:`slicings`). 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 ``...``.

	In typical use, ``...`` as the ``Ellipsis`` object appears in a few different
	places, for instance:

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

	- 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, for instance:

	- Doctest's :const:`ELLIPSIS <doctest.ELLIPSIS>`, as a pattern for missing content.

	- 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
	``Ellipsis``.


		.. _bltin-notimplemented-object:

Expand Down

11 changes: 9 additions & 2 deletions Doc/library/typing.rst

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down Expand Up		@@ -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, ...]``::

Expand Down Expand Up		@@ -1154,6 +1159,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 <annotating-callables>` and
		:class:`ParamSpec` to annotate a higher-order callable which adds, removes,
		or transforms parameters of another
Expand Down

7 changes: 7 additions & 0 deletions Doc/tutorial/controlflow.rst

Show comments 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: ...; ellipsis literal
		.. _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
	: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`.


		.. _tut-match:

Expand Down

Navigation Menu

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[3.13] gh-138307: Update the Ellipsis documentation (GH-138306) #138439

Uh oh!

[3.13] gh-138307: Update the Ellipsis documentation (GH-138306) #138439

Filter by extension

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!