Refactor Sentinel to conform to PEP 661

`repr` parameter removed, explicit repr tests removed

`__repr__` modified to match PEP implementation (removed angle brackets)

Added `module_name` parameter following PEP implementation and tweaking
to use `_caller` helper function.

`name` required support for qualified names to follow PEP implementation.

Added `__reduce__` to track Sentinel by name and module_name.

Added a Sentinel registry to preserve Sentinel identity across multiple
calls to the class. Added tests for this.

Added an import step to allow forward compatibility with other sentinel libraries.
Import step is tested.
This was not required by the PEP but it is required for
typing_extensions to have a forward compatible type.

Added copy and pickle tests.

Updated documentation for Sentinel.

Author: HexDecimal

doc/index.rst

@@ -1030,13 +1030,19 @@ Capsule objects
 Sentinel objects
 ~~~~~~~~~~~~~~~~
 
-.. class:: Sentinel(name, repr=None)
+.. class:: Sentinel(name, module_name=None)
 
-   A type used to define sentinel values. The *name* argument should be the
-   name of the variable to which the return value shall be assigned.
+   A type used to define custom sentinel values.
 
-   If *repr* is provided, it will be used for the :meth:`~object.__repr__`
-   of the sentinel object. If not provided, ``"<name>"`` will be used.
+   *name* should be the qualified name of the variable to which
+   the return value shall be assigned.
+
+   *module_name* is the module where the sentinel is defined.
+   Defaults to the current modules ``__name__``.
+
+   All sentinels with the same *name* and *module_name* have the same identity.
+   Sentinel objects are tested using :py:ref:`is`.
+   Sentinel identity is preserved across :py:mod:`copy` and :py:mod:`pickle`.
 
    Example::
 
@@ -1050,6 +1056,24 @@ Sentinel objects
       ...
       >>> func(MISSING)
 
+   Sentinels defined in a class scope must use fully qualified names.
+
+   Example::
+
+      >>> class MyClass:
+      ...     MISSING = Sentinel('MyClass.MISSING')
+
+   Calling the Sentinel class follows these rules for the return value:
+
+   1. If *name* and *module_name* were used in a previous call then return the same
+      object as that previous call.
+      This preserves the identity of the sentinel.
+   2. Otherwise if *module_name.name* already exists then return that object
+      even if that object is not a :class:`typing_extensions.Sentinel` type.
+      This enables forward compatibility with sentinel types from other libraries
+      (the inverse may not be true.)
+   3. Otherwise a new :class:`typing_extensions.Sentinel` is returned.
+
    .. versionadded:: 4.14.0
 
       See :pep:`661`

src/test_typing_extensions.py

@@ -9269,16 +9269,11 @@ def test_invalid_special_forms(self):
 
 
 class TestSentinels(BaseTestCase):
-    def test_sentinel_no_repr(self):
-        sentinel_no_repr = Sentinel('sentinel_no_repr')
+    SENTINEL = Sentinel("TestSentinels.SENTINEL")
 
-        self.assertEqual(sentinel_no_repr._name, 'sentinel_no_repr')
-        self.assertEqual(repr(sentinel_no_repr), '<sentinel_no_repr>')
-
-    def test_sentinel_explicit_repr(self):
-        sentinel_explicit_repr = Sentinel('sentinel_explicit_repr', repr='explicit_repr')
-
-        self.assertEqual(repr(sentinel_explicit_repr), 'explicit_repr')
+    def test_sentinel_repr(self):
+        self.assertEqual(repr(TestSentinels.SENTINEL), "TestSentinels.SENTINEL")
+        self.assertEqual(repr(Sentinel("sentinel")), "sentinel")
 
     @skipIf(sys.version_info < (3, 10), reason='New unions not available in 3.9')
     def test_sentinel_type_expression_union(self):
@@ -9298,13 +9293,25 @@ def test_sentinel_not_callable(self):
         ):
             sentinel()
 
-    def test_sentinel_not_picklable(self):
-        sentinel = Sentinel('sentinel')
-        with self.assertRaisesRegex(
-            TypeError,
-            "Cannot pickle 'Sentinel' object"
-        ):
-            pickle.dumps(sentinel)
+    def test_sentinel_identity(self):
+        self.assertIs(TestSentinels.SENTINEL, Sentinel("TestSentinels.SENTINEL"))
+        self.assertIs(Sentinel("SENTINEL"), Sentinel("SENTINEL", __name__))
+        self.assertIsNot(TestSentinels.SENTINEL, Sentinel("SENTINEL"))
+
+    def test_sentinel_copy(self):
+        self.assertIs(self.SENTINEL, copy.copy(self.SENTINEL))
+        self.assertIs(self.SENTINEL, copy.deepcopy(self.SENTINEL))
+
+    def test_sentinel_import(self):
+        self.assertIs(Sentinel._import_sentinel("TestSentinels", __name__), TestSentinels)
+        self.assertIs(Sentinel._import_sentinel("TestSentinels.SENTINEL", __name__), TestSentinels.SENTINEL)
+        self.assertIs(Sentinel._import_sentinel("nonexistent", __name__), None)
+        self.assertIs(Sentinel._import_sentinel("TestSentinels.nonexistent", __name__), None)
+
+    def test_sentinel_picklable(self):
+        for proto in range(pickle.HIGHEST_PROTOCOL + 1):
+            self.assertIs(self.SENTINEL, pickle.loads(pickle.dumps(self.SENTINEL, protocol=proto)))
+
 
 
 if __name__ == '__main__':

src/typing_extensions.py

@@ -5,6 +5,7 @@
 import contextlib
 import enum
 import functools
+import importlib
 import inspect
 import io
 import keyword
@@ -4155,25 +4156,65 @@ def evaluate_forward_ref(
             )
 
 
+_sentinel_registry = {}
+
+
 class Sentinel:
-    """Create a unique sentinel object.
+    """A sentinel object.
 
-    *name* should be the name of the variable to which the return value shall be assigned.
+    *name* should be the qualified name of the variable to which
+    the return value shall be assigned.
 
-    *repr*, if supplied, will be used for the repr of the sentinel object.
-    If not provided, "<name>" will be used.
+    *module_name* is the module where the sentinel is defined.
+    Defaults to the current modules ``__name__``.
+
+    All sentinels with the same *name* and *module_name* have the same identity.
+    The ``is`` operator is used to test if an object is a sentinel.
+    Sentinel identity is preserved across copy and pickle.
     """
 
-    def __init__(
-        self,
+    def __new__(
+        cls,
         name: str,
-        repr: typing.Optional[str] = None,
+        module_name: typing.Optional[str] = None,
     ):
-        self._name = name
-        self._repr = repr if repr is not None else f'<{name}>'
+        """Return an object with a consistent identity."""
+        if module_name is None:
+            module_name = _caller(default="")
+
+        registry_key = f"{module_name}-{name}"
+
+        # Check registered sentinels
+        sentinel = _sentinel_registry.get(registry_key, None)
+        if sentinel is not None:
+            return sentinel
+
+        # Import sentinel at module_name.name
+        sentinel = cls._import_sentinel(name, module_name)
+        if sentinel is not None:
+            return _sentinel_registry.setdefault(registry_key, sentinel)
+
+        # Create initial or anonymous sentinel
+        sentinel = super().__new__(cls)
+        sentinel._name = name
+        sentinel._module_name = module_name
+        return _sentinel_registry.setdefault(registry_key, sentinel)
+
+    @staticmethod
+    def _import_sentinel(name: str, module_name: str):
+        """Return object `name` imported from `module_name`, otherwise return None."""
+        if not module_name:
+            return None
+        try:
+            module = importlib.import_module(module_name)
+            return operator.attrgetter(name)(module)
+        except ImportError:
+            return None
+        except AttributeError:
+            return None
 
-    def __repr__(self):
-        return self._repr
+    def __repr__(self) -> str:
+        return self._name
 
     if sys.version_info < (3, 11):
         # The presence of this method convinces typing._type_check
@@ -4188,8 +4229,15 @@ def __or__(self, other):
         def __ror__(self, other):
             return typing.Union[other, self]
 
-    def __getstate__(self):
-        raise TypeError(f"Cannot pickle {type(self).__name__!r} object")
+    def __reduce__(self):
+        """Record where this sentinel is defined."""
+        return (
+            Sentinel,  # Ensure pickle data does not get locked to a subclass
+            (  # Only the location of the sentinel needs to be stored
+                self._name,
+                self._module_name,
+            ),
+        )
 
 
 # Aliases for items that are in typing in all supported versions.