Type hints of built-in classes implemented in C

[andy-maier]

I would like to move our nocaselist package forward to use type hints.

So far, its class NocaseList is based on class list. I would like to keep that. However, using mypy for checking my attempts to move to type hints, I get the error:

nocaselist/_nocaselist.py:290: error: Argument 1 of "__imul__" is incompatible with supertype "list"; supertype defines the argument type as "SupportsIndex"  [override]
nocaselist/_nocaselist.py:290: note: This violates the Liskov substitution principle
nocaselist/_nocaselist.py:290: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#incompatible-overrides

on the method:

    def __imul__(self, number: int) -> 'NocaseList':     # line 290

When I change the type hint for the 'number' parameter to SupportsIndex, the mypy failure changes to:

nocaselist/_nocaselist.py:302: error: Unsupported operand types for >= ("int" and "SupportsIndex")  [operator]
nocaselist/_nocaselist.py:307: error: Unsupported operand types for - ("SupportsIndex" and "int")  [operator]

because apparently SupportsIndex cannot be used in numeric expressions:

    def __imul__(self, number: SupportsIndex) -> 'NocaseList':
        " ... "
        if number <= 0:                  # line 302
            del self[:]
            del self._casefolded_list[:]
        else:
            self_items = list(self)
            for _ in range(0, number - 1):          # line 307
                self.extend(self_items)
        return self

My questions are:

• Why is the number parameter in __mul__, __imul__, __rmul__ of the list class defined as SupportsIndex?
• Is there a way to find the type hints of methods of classes that are implemented in C?
• Why does the Python documentation of most classes / methods / functions not mention their type hints?

PS: I think type hints are one of the less convincing features in Python. It clutters up the source code and the documentation, at nearly no advantage. The fact that type hints of most built-in classes are neither shown in the help command nor in the official Python documentation 6 years / 6 releases after their introduction speaks for itself.

[JelleZijlstra]

• Why is the number parameter in __mul__, __imul__, __rmul__ of the list class defined as SupportsIndex?

Because that's what list accepts at runtime:

>>> from typing import SupportsIndex
>>> class X(SupportsIndex):
...     def __index__(self): return 3
... 
>>> [1] * X()
[1, 1, 1]

In Python code, you can go from a SupportsIndex to an int by doing int().

• Is there a way to find the type hints of methods of classes that are implemented in C?

They are in typeshed: https://github.com/python/typeshed/blob/295a5c3e7a21be975aa5a140ad10e9e8828f4710/stdlib/builtins.pyi#L1010

• Why does the Python documentation of most classes / methods / functions not mention their type hints?

Because the documentation predates typing. We may add typeshed types at some point to the docs, but making that maintainable is a challenge.

[JelleZijlstra]

I don't see anything actionable here.