Python Ellipsis (Three Dots) Constant

This page explains the Ellipsis (three dots) constant in Python, its use cases, and relationships to other built-in constants like True, False, or None.

Ellipsis = three dots

The Ellipsis constant is returned when typing a literal ellipsis ... (three dots) or by typing the keyword Ellipsis:

>>> ...
Ellipsis
>>> Ellipsis
Ellipsis

Both are identical and interchangeable:

>>> ... == Ellipsis
True
>>> ... is Ellipsis
True

That said, typing ellipsis with lowercase e does not work. You will get a NameError:

>>> ellipsis
NameError: name 'ellipsis' is not defined

Ellipsis vs. continuation line prompt

Do not confuse Ellipsis (three dots in Python code) with three dots at the beginning of Python command line, which is the continuation line prompt. For example:

>>> def add_two_ints(x, y):
...     return x + y

The three dots at the beginning of the second line above indicate that the line just continues the function definition from the first line.

Similarly:

>>> buylist = [
...     'apples',
...     'oranges',
...     'bananas',
... ]
>>> buylist
['apples', 'oranges', 'bananas']

These are not the Ellipsis constants. These are Python command line prompts.

EllipsisType

The type of Ellipsis is EllipsisType, which prints as ellipsis (with lowercase e).

>>> a = ...
>>> type(a)
ellipsis
>>> b = Ellipsis
>>> type(b)
ellipsis

Ellipsis is the sole instance of EllipsisType.

No quotes (it is not a string)

Make sure to type the triple dot ... or the keyword Ellipsis without quotes – otherwise you get a string:

>>> three_dots = ...
>>> three_dots_with_quotes = '...'
>>> type(three_dots)
ellipsis
>>> type(three_dots_with_quotes)
str
>>> ... == '...'
False

Ellipsis and True/False

The Ellipsis constant means anything and nothing particular. Passing it to the bool() function returns True:

>>> bool(...)
True

At the same time, it does not equal either True or False:

>>> ... == True
False
>>> ... == False
False

Ellipsis is not None

Ellipsis does not equal and is not None:

>>> ... == None
False
>>> ... is None
False
>>> ... is not None
True

When and how to use Ellipsis

Ellipsis in array slices

Ellipsis has traditionally been used in array slices, notably in numpy multidimensional arrays:

>>> import numpy as np
>>> a = np.array([
...     [[1, 2]],
...     [[3, 4]],
...     [[5, 6]],
... ])
>>> a[...,0]
array([[1],
       [3],
       [5]])
>>> a[:,:,0]
array([[1],
       [3],
       [5]])

Ellipsis as placeholder (like pass)

Ellipsis can be used as placeholder for omitted code – as a "do nothing" code, just like the pass keyword.

For example, this function returns nothing and has no visual output:

>>> def do_nothing_with_three_dots():
...     ...
>>> do_nothing_with_three_dots()

As explained above, the first triple dot on the second line is the continuation line prompt, while the second triple dot is the actual Ellipsis in Python code.

The following function does exactly the same thing (nothing), because three dots and the Ellipsis keyword are interchangeable:

>>> def do_nothing_with_ellipsis():
...     Ellipsis
>>> do_nothing_with_ellipsis()

This function also does nothing, using the pass keyword:

>>> def do_nothing_with_pass():
...     pass
>>> do_nothing_with_pass()

Omitting code and replacing it with ... or Ellipsis or pass can be useful in various situations:

• When debugging, you can omit the code that has no effect on the particular problem.
• When sharing code with others, you can omit the code which is not important to them.
• You can also temporarily replace code with Ellipsis when it is not implemented yet (although in such case it is often better to use the NotImplemented constant or raise NotImplementedError).

Ellipsis as function argument

Ellipsis can be passed as argument to functions just like any other constant or variable.

The difference between Ellipsis and None can be useful when you want to differentiate between passing None and not passing an argument. Just use Ellipsis as default:

>>> def f(a = ...):
...    if a is None:
...	   # This code executes when calling f(None)
...        return 'a specified as None'
...    elif a is ...:
...        # This code executes when calling just f()
...        return 'a not specified'
>>> f(None)
'a specified as None'
>>> f()
'a not specified'

Importing Ellipsis

The Ellipsis constant is built in – you don't need to import it.

Ellipsis in Python versions

In Python 2 ellipsis was only available in slices.

Since Python 3.0 it is available as a built-in constant anywhere in Python.

Since Python 3 it must be spelled ... without spaces. Previously, "by a mere accident of the grammar", it could also be spelled . . . (with spaces between the dots).

Help / docstring

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

Official documentation

Official documentation at docs.python.org