bpo-36972: Add SupportsIndex (GH-13448)

In order to support typing checks calling hex(), oct() and bin() on user-defined classes, a SupportIndex protocol is required. The ability to check these at runtime would be good to add for completeness sake. This is pretty much just a copy of SupportsInt with the names tweaked.

Doc/library/typing.rst

@@ -529,6 +529,12 @@ The module defines the following classes, functions and decorators:
 
     An ABC with one abstract method ``__bytes__``.
 
+.. class:: SupportsIndex
+
+    An ABC with one abstract method ``__index__``.
+
+    .. versionadded:: 3.8
+
 .. class:: SupportsAbs
 
     An ABC with one abstract method ``__abs__`` that is covariant

Lib/test/test_typing.py

@@ -568,6 +568,10 @@ class ProtocolTests(BaseTestCase):
         self.assertIsSubclass(list, typing.Reversible)
         self.assertNotIsSubclass(int, typing.Reversible)
 
+    def test_supports_index(self):
+        self.assertIsSubclass(int, typing.SupportsIndex)
+        self.assertNotIsSubclass(str, typing.SupportsIndex)
+
     def test_protocol_instance_type_error(self):
         with self.assertRaises(TypeError):
             isinstance(0, typing.SupportsAbs)

Lib/typing.py

@@ -74,6 +74,7 @@ __all__ = [
     'SupportsBytes',
     'SupportsComplex',
     'SupportsFloat',
+    'SupportsIndex',
     'SupportsInt',
     'SupportsRound',
 
@@ -1304,6 +1305,14 @@ class SupportsBytes(_Protocol):
         pass
 
 
+class SupportsIndex(_Protocol):
+    __slots__ = ()
+
+    @abstractmethod
+    def __index__(self) -> int:
+        pass
+
+
 class SupportsAbs(_Protocol[T_co]):
     __slots__ = ()
 

Misc/ACKS

@@ -355,6 +355,7 @@ Tom Culliton
 Raúl Cumplido
 Antonio Cuni
 Brian Curtin
+Paul Dagnelie
 Lisandro Dalcin
 Darren Dale
 Andrew Dalke

Misc/NEWS.d/next/Library/2019-05-20-17-08-26.bpo-36972.3l3SGc.rst

@@ -0,0 +1 @@
+Add SupportsIndex protocol to the typing module to allow type checking to detect classes that can be passed to `hex()`, `oct()` and `bin()`.