Improve ellipsis type

The issue names no implementation files or tests; start by locating the current ellipsis definition and the Markdown documentation that describes it. Check Python-version compatibility and type-checking behavior, then confirm that the chosen representation is documented clearly and rejects non-Ellipsis arguments as intended.

The current ellipsis = TypeVar('ellipsis') doesn't behave well with typechecking. It's also unclear in the Markdown docs what ellipsis is supposed to be. It's kind of clear from the context, but not compatible with "real" python types:

from types import EllipsisType
from typing import Protocol, TypeVar

ellipsis = TypeVar('ellipsis')  # This is the current implementation.

class BadProto(Protocol):
    def f(self, ell: ellipsis) -> None: ...  # Error: TypeVar "ellipsis" appears onlly once in generic function signature


class GoodProto(Protocol):
    def f(self, ell: EllipsisType) -> None: ...  # Ok, no error raised.


def some_bad_operation(x: BadProto) -> None:
    x.f('hello')  # Problematic: doesn't raise a type error.

def some_good_operation(x: GoodProto) -> None:
    x.f('hello')  # Good, raises:
    # [Pyright] Argument of type "Literal['hello']" cannot be assigned to parameter "ell" of type "EllipsisType" in function "f"
    #   "Literal['hello']" is incompatible with "EllipsisType"

The downside of EllipsisType is that it's only available in Python 3.10 onwards. However, we have the following:

assert EllipsisType == type(...)
assert EllipsisType == type(Ellipsis)
assert EllipsisType != ...
assert EllipsisType != Ellipsis
assert ellipsis != Ellipsis  # with ellipsis = TypeVar('ellipsis')

It seems to me like it would make sense to change the current ellipsis = TypeVar('ellipsis') to one of the variants that works. I think it would also be a clarification in the documentation to change ellipsis to EllipsisType and maybe have a note somewhere that those using Python < 3.10 can use the equivalent type(...) or type(Ellipsis).

Potentially related to

• #589
• #229