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.

5 files changed, 21 insertions, 0 deletions

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index c2523ed..86a3db8 100644
--- a/Doc/library/typing.rst
+++ b/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
diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py
index a547fe2..c9bfd0c 100644
--- a/Lib/test/test_typing.py
+++ b/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)
diff --git a/Lib/typing.py b/Lib/typing.py
index 530d463..7aab162 100644
--- a/Lib/typing.py
+++ b/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__ = ()
 
diff --git a/Misc/ACKS b/Misc/ACKS
index 6b1fdbc..8f0ecb7 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -355,6 +355,7 @@ Tom Culliton
 Raúl Cumplido
 Antonio Cuni
 Brian Curtin
+Paul Dagnelie
 Lisandro Dalcin
 Darren Dale
 Andrew Dalke
diff --git a/Misc/NEWS.d/next/Library/2019-05-20-17-08-26.bpo-36972.3l3SGc.rst b/Misc/NEWS.d/next/Library/2019-05-20-17-08-26.bpo-36972.3l3SGc.rst
new file mode 100644
index 0000000..da650e8
--- /dev/null
+++ b/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()`.