Update sentinel for PEP 661 changes

Rename Sentinel to sentinel, deprecated old name

Remove module_name parameter

Deprecate subclassing sentinel

Enforce correct sentinel parameters using deprecated overloads

Rename _name attribute to __name__

Rename sentinel in tests, tests passed before making this change

Also add tests for sentinel deprecations

Author: HexDecimal

doc/index.rst

@@ -1071,21 +1071,21 @@ Capsule objects
 Sentinel objects
 ~~~~~~~~~~~~~~~~
 
-.. class:: Sentinel(name, *, module_name=None, repr=None)
+.. class:: sentinel(name, /, *, repr=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.
 
-   *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.
 
+   A sentinel is bound to the module it is created within,
+   sentinels are not equal to similar named sentinels from other modules.
+
    Example::
 
-      >>> from typing_extensions import Sentinel, assert_type
-      >>> MISSING = Sentinel('MISSING')
+      >>> from typing_extensions import sentinel, assert_type
+      >>> MISSING = sentinel('MISSING')
       >>> def func(arg: int | MISSING = MISSING) -> None:
       ...     if arg is MISSING:
       ...         assert_type(arg, MISSING)
@@ -1099,7 +1099,7 @@ Sentinel objects
    Example::
 
       >>> class MyClass:
-      ...     MISSING = Sentinel('MyClass.MISSING')
+      ...     MISSING = sentinel('MyClass.MISSING')
 
    .. versionadded:: 4.14.0
 

src/test_typing_extensions.py

@@ -102,6 +102,7 @@
     reveal_type,
     runtime,
     runtime_checkable,
+    sentinel,
     type_repr,
 )
 
@@ -9541,42 +9542,42 @@ def test_invalid_special_forms(self):
 
 
 class TestSentinels(BaseTestCase):
-    SENTINEL = Sentinel("TestSentinels.SENTINEL")
+    SENTINEL = sentinel("TestSentinels.SENTINEL")
 
     def test_sentinel_no_repr(self):
-        sentinel_no_repr = Sentinel('sentinel_no_repr')
+        sentinel_no_repr = sentinel('sentinel_no_repr')
 
-        self.assertEqual(sentinel_no_repr._name, 'sentinel_no_repr')
-        self.assertEqual(repr(sentinel_no_repr), '<sentinel_no_repr>')
+        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')
+        sentinel_explicit_repr = sentinel('sentinel_explicit_repr', repr='explicit_repr')
 
         self.assertEqual(repr(sentinel_explicit_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')
+        sentinel_type = sentinel('sentinel')
 
-        def func1(a: int | sentinel = sentinel): pass
-        def func2(a: sentinel | int = sentinel): pass
+        def func1(a: int | sentinel_type = sentinel_type): pass
+        def func2(a: sentinel_type | int = sentinel_type): pass
 
-        self.assertEqual(func1.__annotations__['a'], Union[int, sentinel])
-        self.assertEqual(func2.__annotations__['a'], Union[sentinel, int])
+        self.assertEqual(func1.__annotations__['a'], Union[int, sentinel_type])
+        self.assertEqual(func2.__annotations__['a'], Union[sentinel_type, int])
 
     def test_sentinel_not_callable(self):
-        sentinel = Sentinel('sentinel')
+        sentinel_ = sentinel('sentinel')
         with self.assertRaisesRegex(
             TypeError,
-            "'Sentinel' object is not callable"
+            "'sentinel' object is not callable"
         ):
-            sentinel()
+            sentinel_()
 
     def test_sentinel_copy_identity(self):
         self.assertIs(self.SENTINEL, copy.copy(self.SENTINEL))
         self.assertIs(self.SENTINEL, copy.deepcopy(self.SENTINEL))
 
-        anonymous_sentinel = Sentinel("anonymous_sentinel")
+        anonymous_sentinel = sentinel("anonymous_sentinel")
         self.assertIs(anonymous_sentinel, copy.copy(anonymous_sentinel))
         self.assertIs(anonymous_sentinel, copy.deepcopy(anonymous_sentinel))
 
@@ -9585,14 +9586,25 @@ def test_sentinel_picklable_qualified(self):
             self.assertIs(self.SENTINEL, pickle.loads(pickle.dumps(self.SENTINEL, protocol=proto)))
 
     def test_sentinel_picklable_anonymous(self):
-        anonymous_sentinel = Sentinel("anonymous_sentinel")  # Anonymous sentinel can not be pickled
+        anonymous_sentinel = sentinel("anonymous_sentinel")  # Anonymous sentinel can not be pickled
         for proto in range(pickle.HIGHEST_PROTOCOL + 1):
             with self.assertRaisesRegex(
                 pickle.PicklingError,
                 r"attribute lookup anonymous_sentinel on \w+ failed|not found as \w+.anonymous_sentinel"
             ):
                 self.assertIs(anonymous_sentinel, pickle.loads(pickle.dumps(anonymous_sentinel, protocol=proto)))
 
+    def test_sentinel_deprecated(self):
+        with self.assertWarnsRegex(DeprecationWarning, r"Subclassing sentinel is forbidden by PEP 661"):
+            class SentinelSubclass(Sentinel):
+                pass
+
+        with self.assertWarnsRegex(DeprecationWarning, r"Sentinel was renamed to typing_extensions.sentinel"):
+            my_sentinel = Sentinel(name="my_sentinel")
+        with self.assertWarnsRegex(DeprecationWarning, r"Setting attributes on sentinel is deprecated"):
+            my_sentinel.foo = "bar"
+
+
 def load_tests(loader, tests, pattern):
     import doctest
     tests.addTests(doctest.DocTestSuite(typing_extensions))

src/typing_extensions.py

@@ -91,6 +91,7 @@
     'overload',
     'override',
     'Protocol',
+    'sentinel',
     'Sentinel',
     'reveal_type',
     'runtime',
@@ -386,30 +387,45 @@ def _caller(depth=1, default='__main__'):
     return None
 
 
-class Sentinel:
+class sentinel:
     """Create a unique sentinel object.
 
     *name* should be the 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__``.
-
     *repr*, if supplied, will be used for the repr of the sentinel object.
     If not provided, "<name>" will be used.
     """
 
+    @overload
+    def __init__(self, name: str, /, *, repr: typing.Optional[str] = None): ...
+
+    @overload
+    @deprecated("'name' must be positional-only, 'repr' must be keyword-only.")
+    def __init__(self, name: str, repr: typing.Optional[str] = None): ...
+
     def __init__(
         self,
         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}>'
+        self.__name__ = name
+        self._repr = repr if repr is not None else name
 
         # For pickling as a singleton:
-        self.__module__ = module_name if module_name is not None else _caller()
+        self.__module__ = _caller()
+
+    @deprecated("Subclassing sentinel is forbidden by PEP 661")
+    def __init_subclass__(cls):
+        super().__init_subclass__()
+
+    def __setattr__(self, attr: str, value: object) -> None:
+        if attr not in {"__name__", "_repr", "__module__"}:
+            warnings.warn(
+                "Setting attributes on sentinel is deprecated",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        super().__setattr__(attr, value)
 
     def __repr__(self):
         return self._repr
@@ -430,10 +446,17 @@ def __ror__(self, other):
 
     def __reduce__(self) -> str:
         """Reduce this sentinel to a singleton."""
-        return self._name  # Module is taken from the __module__ attribute
+        return self.__name__  # Module is taken from the __module__ attribute
+
+with warnings.catch_warnings():  # Allow sentinel subclass for backwards compatibility
+    warnings.simplefilter("ignore")
+
+    @deprecated("""Sentinel was renamed to typing_extensions.sentinel""")
+    class Sentinel(sentinel):
+        pass
 
+_marker = sentinel("sentinel")
 
-_marker = Sentinel("sentinel", module_name=__name__)
 
 # The functions below are modified copies of typing internal helpers.
 # They are needed by _ProtocolMeta and they provide support for PEP 646.