Support __closed__ and __extra_items__ 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, supporting the `closed` keyword argument and the
+  special `__extra_items__` key for TypedDict. Patch by Zixuan James Li.
 - Add support for PEP 742, adding `typing_extensions.TypeIs`. Patch
   by Jelle Zijlstra.
 - Drop runtime error when a read-only `TypedDict` item overrides a mutable

doc/index.rst

@@ -394,6 +394,15 @@ Special typing primitives
       are mutable if they do not carry the :data:`ReadOnly` qualifier.
 
       .. versionadded:: 4.9.0
+    
+    The experimental ``closed`` keyword argument and the special key
+    ``"__extra_items__"`` proposed in :pep:`728` are supported.
+
+    When ``closed`` is unspecified or ``closed=False`` is given,
+    ``"__extra_items__"`` behave like a regular key. Otherwise, this becomes a
+    special key that does not show up in ``__readonly_keys__``,
+    ``__mutable_keys__``, ``__required_keys__``, ``__optional_keys``, or
+    ``__annotations__``.
 
    .. versionchanged:: 4.3.0
 
@@ -427,6 +436,11 @@ Special typing primitives
 
       Support for the :data:`ReadOnly` qualifier was added.
 
+   .. versionchanged:: 4.10.0
+
+      The keyword argument ``closed`` and the special key ``"__extra_items__"``
+      when ``closed=True`` is given were supported.
+
 .. class:: TypeVar(name, *constraints, bound=None, covariant=False,
                    contravariant=False, infer_variance=False, default=...)
 

src/test_typing_extensions.py

@@ -4177,7 +4177,103 @@ 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, closed=True):
+            __extra_items__: 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, closed=True):
+            __extra_items__: 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,
+            "Special key __extra_items__ does not support Required and NotRequired"
+        ):
+            TypedDict("A", {"__extra_items__": Required[int]}, closed=True)
+
+        with self.assertRaisesRegex(
+            TypeError,
+            "Special key __extra_items__ does not support Required and NotRequired"
+        ):
+            TypedDict("A", {"__extra_items__": NotRequired[int]}, closed=True)
+    
+    def test_regular_extra_items(self):
+        class ExtraReadOnly(TypedDict):
+            __extra_items__: ReadOnly[str]
+
+        class ExtraRequired(TypedDict):
+            __extra_items__: Required[str]
+
+        class ExtraNotRequired(TypedDict):
+            __extra_items__: NotRequired[str]
+        
+        self.assertEqual(ExtraReadOnly.__required_keys__, frozenset({'__extra_items__'}))
+        self.assertEqual(ExtraReadOnly.__optional_keys__, frozenset({}))
+        self.assertEqual(ExtraReadOnly.__readonly_keys__, frozenset({'__extra_items__'}))
+        self.assertEqual(ExtraReadOnly.__mutable_keys__, frozenset({}))
+
+        self.assertEqual(ExtraRequired.__required_keys__, frozenset({'__extra_items__'}))
+        self.assertEqual(ExtraRequired.__optional_keys__, frozenset({}))
+        self.assertEqual(ExtraRequired.__readonly_keys__, frozenset({}))
+        self.assertEqual(ExtraRequired.__mutable_keys__, frozenset({'__extra_items__'}))
+
+        self.assertEqual(ExtraNotRequired.__required_keys__, frozenset({}))
+        self.assertEqual(ExtraNotRequired.__optional_keys__, frozenset({'__extra_items__'}))
+        self.assertEqual(ExtraNotRequired.__readonly_keys__, frozenset({}))
+        self.assertEqual(ExtraNotRequired.__mutable_keys__, frozenset({'__extra_items__'}))
+    
+    def test_closed_inheritance(self):
+        class Base(TypedDict, closed=True):
+            __extra_items__: ReadOnly[Union[str, None]]
+        
+        class Child(Base):
+            a: int
+            __extra_items__: int
+
+        class GrandChild(Child, closed=True):
+            __extra_items__: str
+
+        self.assertEqual(Base.__required_keys__, frozenset({}))
+        self.assertEqual(Base.__optional_keys__, frozenset({}))
+        self.assertEqual(Base.__readonly_keys__, frozenset({}))
+        self.assertEqual(Base.__mutable_keys__, frozenset({}))
+
+        self.assertEqual(Child.__required_keys__, frozenset({'a', "__extra_items__"}))
+        self.assertEqual(Child.__optional_keys__, frozenset({}))
+        self.assertEqual(Child.__readonly_keys__, frozenset({}))
+        self.assertEqual(Child.__mutable_keys__, frozenset({'a', "__extra_items__"}))
+
+        self.assertEqual(GrandChild.__required_keys__, frozenset({'a', "__extra_items__"}))
+        self.assertEqual(GrandChild.__optional_keys__, frozenset({}))
+        self.assertEqual(GrandChild.__readonly_keys__, frozenset({}))
+        self.assertEqual(GrandChild.__mutable_keys__, frozenset({'a', "__extra_items__"}))
+
+        self.assertEqual(Base.__annotations__, {"__extra_items__": ReadOnly[Union[str, None]]})
+        self.assertEqual(Child.__annotations__, {"__extra_items__": int, "a": int})
+        self.assertEqual(GrandChild.__annotations__, {"__extra_items__": str, "a": int})
+
+        self.assertTrue(Base.__closed__)
+        self.assertFalse(Child.__closed__)
+        self.assertTrue(GrandChild.__closed__)
+        
 
 class AnnotatedTests(BaseTestCase):
 

src/typing_extensions.py

@@ -875,7 +875,7 @@ def _get_typeddict_qualifiers(annotation_type):
                 break
 
     class _TypedDictMeta(type):
-        def __new__(cls, name, bases, ns, *, total=True):
+        def __new__(cls, name, bases, ns, *, total=True, closed=False):
             """Create new typed dict class object.
 
             This method is called when TypedDict is subclassed,
@@ -934,6 +934,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 closed and annotation_key == "__extra_items__":
+                    if Required in qualifiers or NotRequired in qualifiers:
+                        raise TypeError(
+                            f"Special key __extra_items__ does not support"
+                            " Required and NotRequired"
+                        )
+                    continue
                 if Required in qualifiers:
                     required_keys.add(annotation_key)
                 elif NotRequired in qualifiers:
@@ -956,6 +963,7 @@ def __new__(cls, name, bases, ns, *, total=True):
             tp_dict.__mutable_keys__ = frozenset(mutable_keys)
             if not hasattr(tp_dict, '__total__'):
                 tp_dict.__total__ = total
+            tp_dict.__closed__ = closed
             return tp_dict
 
         __call__ = dict  # static method
@@ -969,7 +977,7 @@ def __subclasscheck__(cls, other):
     _TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {})
 
     @_ensure_subclassable(lambda bases: (_TypedDict,))
-    def TypedDict(typename, fields=_marker, /, *, total=True, **kwargs):
+    def TypedDict(typename, fields=_marker, /, *, total=True, closed=False, **kwargs):
         """A simple typed namespace. At runtime it is equivalent to a plain dict.
 
         TypedDict creates a dictionary type such that a type checker will expect all
@@ -1050,7 +1058,7 @@ class Point2D(TypedDict):
             # Setting correct module is necessary to make typed dict classes pickleable.
             ns['__module__'] = module
 
-        td = _TypedDictMeta(typename, (), ns, total=total)
+        td = _TypedDictMeta(typename, (), ns, total=total, closed=closed)
         td.__orig_bases__ = (TypedDict,)
         return td