Support __extra__ for PEP 728.

Signed-off-by: Zixuan James Li <[email protected]>

Author: PIG208

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+- Add support for PEP 728, making `__extra__` a reserved key for TypedDict.
+  Patch by Zixuan James Li.
 - Speedup `issubclass()` checks against simple runtime-checkable protocols by
   around 6% (backporting https://github.com/python/cpython/pull/112717, by Alex
   Waygood).

doc/index.rst

@@ -388,6 +388,10 @@ Special typing primitives
       are mutable if they do not carry the :data:`ReadOnly` qualifier.
 
       .. versionadded:: 4.9.0
+    
+    The experimental reserved key `__extra__` proposed in :pep:`728` is
+    supported. It annotates the value type of the additional keys that might
+    appear in the TypedDict.
 
    .. versionchanged:: 4.3.0
 
@@ -421,6 +425,10 @@ Special typing primitives
 
       Support for the :data:`ReadOnly` qualifier was added.
 
+   .. versionchanged:: 4.10.0
+
+      The reserved key `__extra__` was supported.
+
 .. class:: TypeVar(name, *constraints, bound=None, covariant=False,
                    contravariant=False, infer_variance=False, default=...)
 

src/test_typing_extensions.py

@@ -4171,6 +4171,43 @@ class AllTheThings(TypedDict):
         self.assertEqual(AllTheThings.__optional_keys__, frozenset({'c', 'd'}))
         self.assertEqual(AllTheThings.__readonly_keys__, frozenset({'a', 'b', 'c'}))
         self.assertEqual(AllTheThings.__mutable_keys__, frozenset({'d'}))
+    
+    def test_extra_keys_non_readonly(self):
+        class Base(TypedDict):
+            __extra__: str
+        
+        class Child(Base):
+            a: int
+        
+        self.assertEqual(Child.__required_keys__, frozenset({'a'}))
+        self.assertEqual(Child.__optional_keys__, frozenset({}))
+        self.assertEqual(Child.__readonly_keys__, frozenset({}))
+        self.assertEqual(Child.__mutable_keys__, frozenset({'a'}))
+
+    def test_extra_keys_readonly(self):
+        class Base(TypedDict):
+            __extra__: ReadOnly[str]
+        
+        class Child(Base):
+            a: int
+        
+        self.assertEqual(Child.__required_keys__, frozenset({'a'}))
+        self.assertEqual(Child.__optional_keys__, frozenset({}))
+        self.assertEqual(Child.__readonly_keys__, frozenset({}))
+        self.assertEqual(Child.__mutable_keys__, frozenset({'a'}))
+    
+    def test_extra_key_required(self):
+        with self.assertRaisesRegex(
+            TypeError,
+            "Reserved key __extra__ does not support Required and NotRequired"
+        ):
+            TypedDict("A", {"__extra__": Required[int]})
+
+        with self.assertRaisesRegex(
+            TypeError,
+            "Reserved key __extra__ does not support Required and NotRequired"
+        ):
+            TypedDict("A", {"__extra__": NotRequired[int]})
 
 
 class AnnotatedTests(BaseTestCase):

src/typing_extensions.py

@@ -933,6 +933,13 @@ def __new__(cls, name, bases, ns, *, total=True):
             for annotation_key, annotation_type in own_annotations.items():
                 qualifiers = set(_get_typeddict_qualifiers(annotation_type))
 
+                if annotation_key == "__extra__":
+                    if Required in qualifiers or NotRequired in qualifiers:
+                        raise TypeError(
+                            f"Reserved key __extra__ does not support"
+                            " Required and NotRequired"
+                        )
+                    continue
                 if Required in qualifiers:
                     required_keys.add(annotation_key)
                 elif NotRequired in qualifiers: