Python Ellipsis (triple dots): What is it, How to Use

Chances are, you never ran into the Python ellipsis, consisting of three consecutive dots (…). I did, and I decided to do some research and find out more about this somewhat mysterious language element. Let’s go and explore together!

What is the Python ellipsis?

An ellipsis is built from three consecutive dots, like this: …

It’s a well know language construct in many western languages. But it’s also part of the Python programming language! Let’s inspect this thing in the REPL:

>>> ...
Ellipsis
>>> # OK, it's an object (like everything in Python)
>>> type(...)
<class 'ellipsis'>
>>> help(...)

Help on ellipsis object:

class ellipsis(object)
 |  Methods defined here:
 |  
 |  __getattribute__(self, name, /)
 |      Return getattr(self, name).
 |  
 |  __reduce__(...)
 |      Helper for pickle.
 |  
 |  __repr__(self, /)
 |      Return repr(self).
 |  
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |  
 |  __new__(*args, **kwargs) from builtins.type
 |      Create and return a new object.  See help(type) for accurate signature.

There seems to be one instance of the class ellipsis, called Ellipsis. That’s all not very helpful, so let’s see what the official documentation has to say about this mysterious thing. Turns out there’s not much there, either:

‘Special value used mostly in conjunction with extended slicing syntax for user-defined container data types.’

Looks like this ain’t gonna be a walk in the park. We’ll need to do more digging! After some searching, I found out the following uses for the Ellipsis object.

Where do we use the Python ellipsis?

Python ellipsis as a placeholder

You can use it as a placeholder, e.g. when you intend to fill in a Python function later on, but still want to have a valid syntax:

def todo():
    ...

Many people use pass in such cases, but this looks nicer (personal taste, of course), and there are no real downsides I can think of.

The ellipsis in NumPy slice notation

The most useful application of the ellipsis is in the numpy library. With NumPy, you can slice multiple dimensions at once by using commas. To demonstrate, first create a simple three-dimensional matrix:

>>> x = np.array([   [ [1],[2],[3] ], [ [4],[5],[6] ]   ])

Now these two operations are equivalent:

>>> x[:,:]
array([[[1],
        [2],
        [3]],

       [[4],
        [5],
        [6]]])

>>> x[...]
array([[[1],
        [2],
        [3]],

       [[4],
        [5],
        [6]]])

To get all the data elements from the first index of the first dimension:

>>> x[1, ... ]
array([[1],
       [2],
       [3]])

You can find a more thorough explanation on this blog and the NumPy docs.

End of queue marker

Some use the ellipsis to mark the end of a queue. It makes sense:

• You don’t need to create a custom object
• It’s not something that you usually encounter in queues, so it’s unique enough to be an end-of-queue marker

Circular references

When creating circular references, Python shows an ellipsis in the REPL:

>>>a = [0, 1]
>>> a[0] = a
>>> a
[[...], 1]

This doesn’t mean Python replaces the reference with an ellipsis, it just shows one instead of crashing in an infinite loop and/or filling up your screen. You can test this yourself. You can keep asking for nested objects, and it will still result in the original a:

>>>a = [0, 1]
>>> a[0] = a
>>> a[0][0][0][0][0][0][0][0][0][0]
[[...], 1]