Add Sentinel repr keyword and ensure backwards compatibility

Adds tests for both the keyword and old positional repr parameters

Author: HexDecimal

doc/index.rst

@@ -1030,7 +1030,7 @@ Capsule objects
 Sentinel objects
 ~~~~~~~~~~~~~~~~
 
-.. class:: Sentinel(name, module_name=None)
+.. class:: Sentinel(name, module_name=None, *, repr=None)
 
    A type used to define custom sentinel values.
 
@@ -1040,6 +1040,10 @@ Sentinel objects
    *module_name* is the module where the sentinel is defined.
    Defaults to the current modules ``__name__``.
 
+   If *repr* is provided, it will be used for the :meth:`~object.__repr__`
+   of the sentinel object. If not provided, *name* will be used.
+   Only the initial definition of the sentinel can configure *repr*.
+
    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`.

src/test_typing_extensions.py

@@ -9275,6 +9275,20 @@ def test_sentinel_repr(self):
         self.assertEqual(repr(TestSentinels.SENTINEL), "TestSentinels.SENTINEL")
         self.assertEqual(repr(Sentinel("sentinel")), "sentinel")
 
+    def test_sentinel_explicit_repr(self):
+        sentinel_explicit_repr = Sentinel("sentinel_explicit_repr", repr="explicit_repr")
+        self.assertEqual(repr(sentinel_explicit_repr), "explicit_repr")
+        self.assertEqual(repr(Sentinel("sentinel_explicit_repr")), "explicit_repr")
+
+    def test_sentinel_explicit_repr_deprecated(self):
+        with self.assertWarnsRegex(
+            DeprecationWarning,
+            r"Use keyword parameter repr='explicit_repr' instead"
+        ):
+            deprecated_repr = Sentinel("deprecated_repr", "explicit_repr")
+        self.assertEqual(repr(deprecated_repr), "explicit_repr")
+        self.assertEqual(repr(Sentinel("deprecated_repr")), "explicit_repr")
+
     @skipIf(sys.version_info < (3, 10), reason='New unions not available in 3.9')
     def test_sentinel_type_expression_union(self):
         sentinel = Sentinel('sentinel')

src/typing_extensions.py

@@ -4168,6 +4168,10 @@ class Sentinel:
     *module_name* is the module where the sentinel is defined.
     Defaults to the current modules ``__name__``.
 
+    *repr*, if supplied, will be used for the repr of the sentinel object.
+    If not provided, *name* will be used.
+    Only the initial definition of the sentinel can configure *repr*.
+
     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.
@@ -4177,8 +4181,27 @@ def __new__(
         cls,
         name: str,
         module_name: typing.Optional[str] = None,
+        *,
+        repr: typing.Optional[str] = None,
     ):
         """Return an object with a consistent identity."""
+        if module_name is not None and repr is None:
+            # 'repr' used to be the 2nd positional argument but is now 'module_name'
+            # Test if 'module_name' is a module or is the old 'repr' argument
+            # Use 'repr=name' to suppress this check
+            try:
+                importlib.import_module(module_name)
+            except Exception:
+                repr = module_name
+                module_name = None
+                warnings.warn(
+                    "'repr' as a positional argument could be mistaken for the sentinels"
+                    " 'module_name'."
+                    f" Use keyword parameter repr={repr!r} instead.",
+                    category=DeprecationWarning,
+                    stacklevel=2,
+                )
+
         if module_name is None:
             module_name = _caller(default="")
 
@@ -4198,6 +4221,7 @@ def __new__(
         sentinel = super().__new__(cls)
         sentinel._name = name
         sentinel._module_name = module_name
+        sentinel._repr = repr if repr is not None else name
         return _sentinel_registry.setdefault(registry_key, sentinel)
 
     @staticmethod
@@ -4214,7 +4238,7 @@ def _import_sentinel(name: str, module_name: str):
             return None
 
     def __repr__(self) -> str:
-        return self._name
+        return self._repr
 
     if sys.version_info < (3, 11):
         # The presence of this method convinces typing._type_check
@@ -4232,7 +4256,8 @@ def __ror__(self, other):
     @classmethod
     def _unpickle_fetch_sentinel(cls, name: str, module_name: str):
         """Unpickle using the sentinels location."""
-        return cls(name, module_name)
+        # Explicit repr=name because a saved module_name is known to be valid
+        return cls(name, module_name, repr=name)
 
     def __reduce__(self):
         """Record where this sentinel is defined."""