Merge branch 'main' into typealiastype-writable-module

Author: ericmarkmartin

CHANGELOG.md

@@ -3,6 +3,8 @@
 - Make `typing_extensions.TypeAliasType`'s `__module__` attribute writable.
   Backport of CPython PR
   [#149172](https://github.com/python/cpython/pull/149172).
+- Fix setting of `__required_keys__` and `__optional_keys__` when inheriting
+  keys with the same name.
 - Fix incorrect behaviour on Python 3.9 and Python 3.10 that meant that
   calling `isinstance` with `typing_extensions.Concatenate[...]` or
   `typing_extensions.Unpack[...]` as the first argument could have a different

doc/index.rst

@@ -65,6 +65,10 @@ version from which features were backported; for example,
 ``typing_extensions`` 3.10.0.0 was meant to reflect ``typing`` as of
 Python 3.10.0. During this period, no changelog was maintained.
 
+In the documentation below, for each object added since version 4.0
+there is a note indicating the version in which it was added. Objects
+for which no such note is present have been present since before version 4.0.
+
 Runtime use of types
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -1071,18 +1075,17 @@ Capsule objects
 Sentinel objects
 ~~~~~~~~~~~~~~~~
 
-.. class:: Sentinel(name, repr=None)
+.. class:: sentinel(name, /)
 
    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.
 
-   If *repr* is provided, it will be used for the :meth:`~object.__repr__`
-   of the sentinel object. If not provided, ``"<name>"`` will be used.
+   Assigning attributes to a sentinel is deprecated.
 
    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)
@@ -1095,6 +1098,18 @@ Sentinel objects
 
       See :pep:`661`
 
+   .. versionchanged:: 4.16.0
+
+      The implementation of this class has been updated to conform to
+      the accepted version of :pep:`661`.
+
+      Now supports pickle and will be reduced as a singleton.
+      Renamed from `Sentinel` to `sentinel`, `Sentinel` is deprecated.
+      Automatic `repr` string no longer has angle brackets.
+      `repr` parameter was deprecated.
+      `name` as a keyword is deprecated.
+      Subclassing and attribute assignment are deprecated.
+
 
 Pure aliases
 ~~~~~~~~~~~~

src/test_typing_extensions.py

@@ -102,6 +102,7 @@
     reveal_type,
     runtime,
     runtime_checkable,
+    sentinel,
     type_repr,
 )
 
@@ -4642,6 +4643,47 @@ class ChildWithInlineAndOptional(Untotal, Inline):
                     class Wrong(*bases):
                         pass
 
+    def test_keys_inheritance_with_same_name(self):
+        class NotTotal(TypedDict, total=False):
+            a: int
+
+        class Total(NotTotal):
+            a: int
+
+        self.assertEqual(NotTotal.__required_keys__, frozenset())
+        self.assertEqual(NotTotal.__optional_keys__, frozenset(['a']))
+        self.assertEqual(Total.__required_keys__, frozenset(['a']))
+        self.assertEqual(Total.__optional_keys__, frozenset())
+
+        class Base(TypedDict):
+            a: NotRequired[int]
+            b: Required[int]
+
+        class Child(Base):
+            a: Required[int]
+            b: NotRequired[int]
+
+        self.assertEqual(Base.__required_keys__, frozenset(['b']))
+        self.assertEqual(Base.__optional_keys__, frozenset(['a']))
+        self.assertEqual(Child.__required_keys__, frozenset(['a']))
+        self.assertEqual(Child.__optional_keys__, frozenset(['b']))
+
+    def test_multiple_inheritance_with_same_key(self):
+        class Base1(TypedDict):
+            a: NotRequired[int]
+
+        class Base2(TypedDict):
+            a: Required[str]
+
+        class Child(Base1, Base2):
+            pass
+
+        # Last base wins
+        self.assertEqual(Child.__annotations__, {'a': Required[str]})
+        self.assertEqual(Child.__required_keys__, frozenset(['a']))
+        self.assertEqual(Child.__optional_keys__, frozenset())
+
+
     def test_closed_values(self):
         class Implicit(TypedDict): ...
         class ExplicitTrue(TypedDict, closed=True): ...
@@ -9542,42 +9584,71 @@ def test_invalid_special_forms(self):
 
 
 class TestSentinels(BaseTestCase):
+    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')
+    def test_sentinel_deprecated_explicit_repr(self):
+        with self.assertWarnsRegex(DeprecationWarning, r"'repr' parameter is deprecated and will be removed"):
+            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_()
+
+    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")
+        self.assertIs(anonymous_sentinel, copy.copy(anonymous_sentinel))
+        self.assertIs(anonymous_sentinel, copy.deepcopy(anonymous_sentinel))
+
+    def test_sentinel_picklable_qualified(self):
+        for proto in range(pickle.HIGHEST_PROTOCOL + 1):
+            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
+        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 deprecated"):
+            class SentinelSubclass(Sentinel):
+                pass
+        with self.assertRaisesRegex(TypeError, r"First parameter 'name' is required"):
             sentinel()
 
-    def test_sentinel_not_picklable(self):
-        sentinel = Sentinel('sentinel')
-        with self.assertRaisesRegex(
-            TypeError,
-            "Cannot pickle 'Sentinel' object"
-        ):
-            pickle.dumps(sentinel)
+        with self.assertWarnsRegex(DeprecationWarning, r"Passing 'name' as a keyword argument is deprecated"):
+            my_sentinel = Sentinel(name="my_sentinel")
+        with self.assertWarnsRegex(DeprecationWarning, r"Setting attribute 'foo' on sentinel objects is deprecated"):
+            my_sentinel.foo = "bar"
+
 
 def load_tests(loader, tests, pattern):
     import doctest