# Ellipsis documentation

**URL:** <https://discuss.python.org/t/ellipsis-documentation/99481>\
**Category:** Documentation\
**Created:** [July 20, 2025, 2:08pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481 "2025-07-20T14:08:40Z")\
**Posts on this page:** 14\
**Page:** 1

<div class="post-metadata">

**Author:** ![adorilson](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/adorilson/32/16927_2.png) [@adorilson](https://discuss.python.org/u/adorilson)\
**Post date:** [July 20, 2025, 2:08pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/1 "2025-07-20T14:08:40Z")

</div>

The [Ellipsis built-in constant’s documentation](https://docs.python.org/3/library/constants.html#Ellipsis) says:

```python
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](https://docs.python.org/3/tutorial/controlflow.html#pass-statements) and replacing the snippet above with a `pass` reference that includes a link.

---

<div class="post-metadata">

**Author:** ![Jelle](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jelle/32/1049_2.png) [@Jelle](https://discuss.python.org/u/Jelle)\
**Post date:** [July 20, 2025, 2:39pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/2 "2025-07-20T14:39:17Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![adorilson](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/adorilson/32/16927_2.png) [@adorilson](https://discuss.python.org/u/adorilson)\
**Post date:** [July 20, 2025, 4:57pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/3 "2025-07-20T16:57:27Z")

</div>

> [@Jelle](#):
>
> Ellipsis also has some uses in the type system (arbitrary-length tuples like `tuple[int, ...]` and callables with unspecified signatures like `Callable[..., int]`).

Nice. I found it: [typing — Support for type hints — Python 3.13.5 documentation](https://docs.python.org/3/library/typing.html#annotating-callable-objects)

> [@Jelle](#):
>
> I have no idea whether those uses are more or less common than use for extended slicing with things like numpy arrays,

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

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

---

<div class="post-metadata">

**Author:** ![tjreedy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/tjreedy/32/137_2.png) [@tjreedy](https://discuss.python.org/u/tjreedy)\
**Post date:** [July 21, 2025, 1:30pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/4 "2025-07-21T13:30:28Z")

</div>

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](https://docs.python.org/3/genindex-Symbols.html), `...` has 4 links, and one should be added for the type use.

---

<div class="post-metadata">

**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/nedbat/32/8744_2.png) [@nedbat](https://discuss.python.org/u/nedbat)\
**Post date:** [July 21, 2025, 1:46pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/5 "2025-07-21T13:46:52Z")

</div>

> [@tjreedy](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![guido](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/guido/32/21_2.png) [@guido](https://discuss.python.org/u/guido)\
**Post date:** [July 21, 2025, 10:52pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/6 "2025-07-21T22:52:38Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![m-f-h](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/m-f-h/32/26022_2.png) [@m-f-h](https://discuss.python.org/u/m-f-h)\
**Post date:** [July 22, 2025, 4:17am UTC](https://discuss.python.org/t/ellipsis-documentation/99481/7 "2025-07-22T04:17:16Z")

</div>

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…)

---

<div class="post-metadata">

**Author:** ![peterc](https://avatars.discourse-cdn.com/v4/letter/p/f9ae1b/32.png) [@peterc](https://discuss.python.org/u/peterc)\
**Post date:** [July 22, 2025, 7:43am UTC](https://discuss.python.org/t/ellipsis-documentation/99481/8 "2025-07-22T07:43:26Z")

</div>

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

```python
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**

---

<div class="post-metadata">

**Author:** ![adorilson](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/adorilson/32/16927_2.png) [@adorilson](https://discuss.python.org/u/adorilson)\
**Post date:** [July 22, 2025, 2:03pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/9 "2025-07-22T14:03:10Z")

</div>

> [@tjreedy](#):
>
> The special use in the type system should be documented. In the [symbol index](https://docs.python.org/3/genindex-Symbols.html), `...` has 4 links, and one should be added for the type use.

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](https://docs.python.org/3/library/stdtypes.html#the-ellipsis-object) we have:

```python
The Ellipsis Object

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

```

When I read this, I think something like:

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

---

<div class="post-metadata">

**Author:** ![Jelle](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jelle/32/1049_2.png) [@Jelle](https://discuss.python.org/u/Jelle)\
**Post date:** [July 22, 2025, 2:41pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/10 "2025-07-22T14:41:10Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![mauve](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/mauve/32/3257_2.png) [@mauve](https://discuss.python.org/u/mauve)\
**Post date:** [July 23, 2025, 10:42am UTC](https://discuss.python.org/t/ellipsis-documentation/99481/11 "2025-07-23T10:42:30Z")

</div>

> [@adorilson](#):
>
> When I read this, I think something like:
> 
> ```python
> >>> l = [1,2,3,4,5]
> >>> l[1...4]
> 
> ```
> 
> How, in stdlib, can Ellipsis be used by slicing?

The numpy multidimensional slicing syntax is like

```python
img[..., :3]

```

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

```python
img[:, :, :3]

```

> [@Jelle](#):
>
> The “extended slicing” use isn’t in the stdlib; it’s for multidimensional numpy-style arrays.

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

```python
>>> 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

```

---

<div class="post-metadata">

**Author:** ![adorilson](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/adorilson/32/16927_2.png) [@adorilson](https://discuss.python.org/u/adorilson)\
**Post date:** [July 23, 2025, 11:47am UTC](https://discuss.python.org/t/ellipsis-documentation/99481/12 "2025-07-23T11:47:26Z")

</div>

> [@mauve](#):
>
> Could be added though, `memoryview` can be multidimensional, it just doesn’t support multidimensional slicing apparently.

Maybe you could put this in the ideas category.

---

<div class="post-metadata">

**Author:** ![MegaIng](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/megaing/32/16162_2.png) [@MegaIng](https://discuss.python.org/u/MegaIng)\
**Post date:** [July 23, 2025, 12:17pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/13 "2025-07-23T12:17:35Z")

</div>

> [@Memoryview multi-dimensional slicing support](https://discuss.python.org/t/memoryview-multi-dimensional-slicing-support/52776):
>
> [PEP 3118 – Revising the buffer protocol | peps.python.org](https://peps.python.org/pep-3118/) states: \_\_getitem\_\_ (will support multi-dimensional slicing) \_\_setitem\_\_ (will support multi-dimensional slicing) However: mv = memoryview(b'\x00').cast('b', (1, 1)) mv[:,:1] --------------------------------------------------------------------------- NotImplementedError: multi-dimensional slicing is not implemented Has anyone else missed this? Don’t think much would change if only slicing was to be implemented. However, it might ope…

---

<div class="post-metadata">

**Author:** ![adorilson](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/adorilson/32/16927_2.png) [@adorilson](https://discuss.python.org/u/adorilson)\
**Post date:** [August 31, 2025, 7:35pm UTC](https://discuss.python.org/t/ellipsis-documentation/99481/14 "2025-08-31T19:35:50Z")

</div>

Now, we have a PR for discussion.

> <https://github.com/python/cpython/pull/138306>
>
> After a \[discuss thread\](https://discuss.python.org/t/ellipsis-documentation/994…81), this PR updates the Ellipsis documentation.
> 
> 
> 
> \----
> 📚 Documentation preview 📚: https://cpython-previews--138306.org.readthedocs.build/
