Ellipsis documentation

Documentation
1

The Ellipsis built-in constant’s documentation says:

The same as the ellipsis literal “...”. Special value used mostly in conjunction with extended slicing syntax for user-defined container data types. Ellipsis is the sole instance of the types.EllipsisType type.

The snippet Special value used mostly in conjunction with extended slicing syntax for user-defined container data types isn’t too helpful.

I think using Ellipsis instead of pass is more common, simple and, mainly, it is built-in.

I suggest adding an Ellipsis’ reference to the pass documentation on the tutorial and replacing the snippet above with a pass reference that includes a link.

3 Likes
2

Ellipsis also has some uses in the type system (arbitrary-length tuples like tuple[int, ...] and callables with unspecified signatures like Callable[..., int]). I have no idea whether those uses are more or less common than use for extended slicing with things like numpy arrays, but it seems at least worth mentioning in the docs.

6 Likes
3

Nice. I found it: typing — Support for type hints — Python 3.13.5 documentation

I guess that any use in the standard library is more common than outside of it. :slightly_smiling_face:

Also, we can say something like “in stdlib, Ellipsis is here and here. User-defined data types can define new uses for it.”

5 Likes
4

When the constant Ellipsis is used instead of pass, it has no special meaning to Python. It is just a [EDIT: constant] expression statement, which the compiler optimizes away. Any other constant, None, 42, False, ‘boo’, results in the same code object. ... is used (by some) by analogy its meaning in English and whatever other languages. This culture-language-based style preference of some is not part of the language or stdlib definition and I don’t think it belongs in the official definition docs.

The special use in the type system should be documented. In the symbol index, ... has 4 links, and one should be added for the type use.

2 Likes
5

I think since many people will see ellipses being used where pass used to appear, it will be helpful to mention that usage in the official docs. We can point out that it’s not special in that way, but that it’s used conventionally as a placeholder body.

8 Likes
6

Don’t they signify different intentions by the author? To me, pass means “here a statement is required syntactically but I have nothing to do so I use the syntax reserved for that purpose”. And ... means “I want to do more here but I haven’t had time yet” or “Here goes stuff that you don’t need to care about”.

Or has ... evolved to have a different convention?

11 Likes
7

Using ellipsis instead of “pass” isn’t really a specific use: In that case it’s just an arbitrary expression, you could as well put 0 or 1 or any string or any other expression there. So I think this should not replace the example of a use-case where you could not use just any other expression. “Extended slicing syntax” is a thing (google it!), where the ellipsis has a precise meaning (in short, “include all remaining dimensions entirely”).

(Edit: how to avoid that two single quotes or double quotes are changed from the basic characters to fancy “curly” quotes?! even the < code > tag doesn’t avoid that! Had to write “any string” instead to avoid “” or ‘’ which isn’t valid Python code…)

8

... is also traditionally used in type stubs, and (some) formatters have special casing for elipsis. Ruff formats

def f(): ...


def g():
    pass


def h():
    "any other constant expression"

[1]

And in Python, because of the “consenting adults” principle, we often have conventions instead of language-enforced rules.

  1. though that last case technically isn’t equivalent, since the string gets assigned to h.doc ↩︎

1 Like
9

I’ve seen each case and other sources. My feeling is that “placeholder” is the Ellipsis use’s “superclass”, reflecting “its meaning in English and whatever other languages”, as you said. Sometimes with a special meaning (type system), sometimes without (instead of pass).

Is there some use case where Ellipsis isn’t a placeholder?

On the standard types we have:

The Ellipsis Object

This object is commonly used by slicing (see Slicings).

When I read this, I think something like:

>>> l = [1,2,3,4,5]
>>> l[1...4]

How, in stdlib, can Ellipsis be used by slicing? The “see Slicings” link doesn’t help.

If indeed, the use by slicing could be cited in the symbol index, as well.

1 Like
10

The “extended slicing” use isn’t in the stdlib; it’s for multidimensional numpy-style arrays.

2 Likes
11

The numpy multidimensional slicing syntax is like

img[..., :3]

and means basically : across all other dimensions, so could be sugar for

img[:, :, :3]

Could be added though, memoryview can be multidimensional, it just doesn’t support multidimensional slicing apparently.

>>> memoryview(img)[..., :3]
Traceback (most recent call last):
  File "<python-input-6>", line 1, in <module>
    memoryview(img)[..., :3]
    ~~~~~~~~~~~~~~~^^^^^^^^^
TypeError: memoryview: invalid slice key
>>> memoryview(img)[:, :, :3]
Traceback (most recent call last):
  File "<python-input-7>", line 1, in <module>
    memoryview(img)[:, :, :3]
    ~~~~~~~~~~~~~~~^^^^^^^^^^
NotImplementedError: multi-dimensional slicing is not implemented
2 Likes
12

Maybe you could put this in the ideas category.

13
1 Like
14

Now, we have a PR for discussion.