Implement sentinel objects as types

Adds support for isinstance and match statements

Methods required to make sentinels pretend they are types are no longer necessary

`self._name` replaced with `self.__name__`

Updated tests and documentation

Author: HexDecimal

doc/index.rst

@@ -1067,17 +1067,28 @@ Sentinel objects
    If *repr* is provided, it will be used for the :meth:`~object.__repr__`
    of the sentinel object. If not provided, ``"<name>"`` will be used.
 
+   Sentinels can be tested using :ref:`is`, :func:`isinstance`,
+   or :ref:`match`.
+
    Example::
 
       >>> from typing_extensions import Sentinel, assert_type
       >>> MISSING = Sentinel('MISSING')
-      >>> def func(arg: int | MISSING = MISSING) -> None:
+      >>> def check_identity(arg: int | MISSING = MISSING) -> None:
       ...     if arg is MISSING:
       ...         assert_type(arg, MISSING)
       ...     else:
       ...         assert_type(arg, int)
       ...
-      >>> func(MISSING)
+      >>> check_identity(MISSING)
+      >>> def check_match(arg: int | MISSING = MISSING) -> None:
+      ...     match arg:
+      ...         case MISSING():
+      ...             assert_type(arg, MISSING)
+      ...         case int()
+      ...             assert_type(arg, int)
+      ...
+      >>> check_match(MISSING)
 
    Sentinels defined inside a class scope should use a :term:`qualified name`.
 

src/test_typing_extensions.py

@@ -9546,9 +9546,11 @@ class TestSentinels(BaseTestCase):
     def test_sentinel_no_repr(self):
         sentinel_no_repr = Sentinel('sentinel_no_repr')
 
-        self.assertEqual(sentinel_no_repr._name, 'sentinel_no_repr')
+        self.assertEqual(sentinel_no_repr.__name__, 'sentinel_no_repr')
         self.assertEqual(repr(sentinel_no_repr), '<sentinel_no_repr>')
 
+        self.assertEqual(repr(Sentinel), "<class 'typing_extensions.Sentinel'>")
+
     def test_sentinel_explicit_repr(self):
         sentinel_explicit_repr = Sentinel('sentinel_explicit_repr', repr='explicit_repr')
 
@@ -9568,7 +9570,7 @@ def test_sentinel_not_callable(self):
         sentinel = Sentinel('sentinel')
         with self.assertRaisesRegex(
             TypeError,
-            "'Sentinel' object is not callable"
+            f"Sentinel object {re.escape(repr(sentinel))} is not callable"
         ):
             sentinel()
 
@@ -9593,6 +9595,21 @@ def test_sentinel_picklable_anonymous(self):
             ):
                 self.assertIs(anonymous_sentinel, pickle.loads(pickle.dumps(anonymous_sentinel, protocol=proto)))
 
+    def test_sentinel_isinstance(self):
+        anonymous_sentinel = Sentinel("anonymous_sentinel")
+        self.assertIsInstance(self.SENTINEL, self.SENTINEL)
+        self.assertIsInstance(anonymous_sentinel, anonymous_sentinel)
+        self.assertNotIsInstance(self.SENTINEL, anonymous_sentinel)
+
+        self.assertIsInstance(self.SENTINEL, object)
+        self.assertIsInstance(self.SENTINEL, type)
+        self.assertNotIsInstance(self.SENTINEL, Sentinel)
+
+        self.assertIsSubclass(self.SENTINEL, object)
+        self.assertIsSubclass(self.SENTINEL, Sentinel)
+        self.assertIsSubclass(self.SENTINEL, self.SENTINEL)
+        self.assertNotIsSubclass(self.SENTINEL, anonymous_sentinel)
+
 def load_tests(loader, tests, pattern):
     import doctest
     tests.addTests(doctest.DocTestSuite(typing_extensions))

src/typing_extensions.py

@@ -159,7 +159,17 @@
 # Added with bpo-45166 to 3.10.1+ and some 3.9 versions
 _FORWARD_REF_HAS_CLASS = "__forward_is_class__" in typing.ForwardRef.__slots__
 
-class Sentinel:
+class _SentinelMeta(type):
+    def __instancecheck__(self, instance) -> bool:
+        return self is instance
+
+    def __repr__(self) -> str:
+        if self is Sentinel:
+            return super().__repr__()  # self._repr missing on base class
+        return self._repr
+
+
+class Sentinel(metaclass=_SentinelMeta):
     """Create a unique sentinel object.
 
     *name* should be the name of the variable to which the return value shall be assigned.
@@ -171,39 +181,28 @@ class Sentinel:
     If not provided, "<name>" will be used.
     """
 
-    def __init__(
-        self,
+    def __new__(
+        cls,
         name: str,
         module_name: typing.Optional[str] = None,
         *,
         repr: typing.Optional[str] = None,
     ):
-        self._name = name
-        self._repr = repr if repr is not None else f'<{name}>'
-
-        # For pickling as a singleton:
-        self.__module__ = module_name if module_name is not None else _caller()
-
-    def __repr__(self):
-        return self._repr
-
-    if sys.version_info < (3, 11):
-        # The presence of this method convinces typing._type_check
-        # that Sentinels are types.
-        def __call__(self, *args, **kwargs):
-            raise TypeError(f"{type(self).__name__!r} object is not callable")
-
-    # Breakpoint: https://github.com/python/cpython/pull/21515
-    if sys.version_info >= (3, 10):
-        def __or__(self, other):
-            return typing.Union[self, other]
-
-        def __ror__(self, other):
-            return typing.Union[other, self]
-
-    def __reduce__(self) -> str:
-        """Reduce this sentinel to a singleton."""
-        return self._name  # Module is taken from the __module__ attribute
+        def stubbed_call(cls, *args, **kwargs):
+            raise TypeError(f"Sentinel object {cls!r} is not callable")
+
+        repr = repr if repr is not None else f'<{name}>'
+        module_name = module_name if module_name is not None else _caller()
+
+        return type(
+            name,
+            (cls,),
+            {
+                "__new__": stubbed_call,  # Disable calling sentinel definitions
+                "_repr": repr,
+                "__module__": module_name,  # For pickling
+            },
+        )
 
 
 _marker = Sentinel("sentinel", __name__)