https://github.com/python/cpython/commit/88665de120d7f89e18774b136f3c898bcfe52c7b commit: 88665de120d7f89e18774b136f3c898bcfe52c7b branch: main author: Adorilson Bezerra <[email protected]> committer: nedbat <[email protected]> date: 2025-09-03T07:27:22-04:00 summary:
gh-138307: Update the Ellipsis documentation (#138306) * 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]> files: M Doc/glossary.rst M Doc/library/constants.rst M Doc/library/stdtypes.rst M Doc/library/typing.rst M Doc/tutorial/controlflow.rst diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 453445211672da..d0fd05cdbdfabe 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -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 diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 04080fd0d865ec..d058ba206c6cd6 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -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 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. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 3320f7c3bba728..5bc8257c37b89b 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5869,13 +5869,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: diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 9dbac8ce75d489..c8eb1d08a1bb2a 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -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 @@ -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, ...]``:: @@ -1162,6 +1167,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 diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 5c0e8f34bf82f4..6d4928f211a69d 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -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 @@ -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: _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
