PEP 655: Integrate feedback from S Pradeep Kumar (#2323)

pep-0655.rst

@@ -45,6 +45,16 @@ different value for ``total``:
 Having to declare two different TypedDict types for this purpose is
 cumbersome.
 
+This PEP introduces two new type qualifiers, ``typing.Required`` and
+``typing.NotRequired``, which allow defining a *single* TypedDict with
+a mix of both required and potentially-missing keys:
+
+::
+
+   class Movie(TypedDict):
+       title: str
+       year: NotRequired[int]
+
 
 Rationale
 =========
@@ -138,6 +148,35 @@ for TypedDict also supports
    Movie = TypedDict('Movie', {'name': str, 'year': NotRequired[int]})
 
 
+Interaction with ``total=False``
+--------------------------------
+
+Any :pep:`589`-style TypedDict declared with ``total=False`` is equivalent
+to a TypedDict with an implicit ``total=True`` definition with all of its
+keys marked as ``NotRequired[]``.
+
+Therefore:
+
+::
+
+   class _MovieBase(TypedDict):  # implicitly total=True
+       title: str
+
+   class Movie(_MovieBase, total=False):
+       year: int
+
+
+is equivalent to:
+
+::
+
+   class _MovieBase(TypedDict):
+       title: str
+
+   class Movie(_MovieBase):
+       year: NotRequired[int]
+
+
 Interaction with ``Annotated[]``
 -----------------------------------
 
@@ -162,8 +201,12 @@ annotations, which may always want ``Annotated[]`` as the outermost annotation.
 [3]_
 
 
+Runtime behavior
+----------------
+
+
 Interaction with ``get_type_hints()``
--------------------------------------
+'''''''''''''''''''''''''''''''''''''
 
 ``typing.get_type_hints(...)`` applied to a TypedDict will by default
 strip out any ``Required[]`` or ``NotRequired[]`` type qualifiers,
@@ -188,7 +231,7 @@ wishes to preserve *all* annotations in the original source:
 
 
 Interaction with ``get_origin()`` and ``get_args()``
-----------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 ``typing.get_origin()`` and ``typing.get_args()`` will be updated to
 recognize ``Required[]`` and ``NotRequired[]``:
@@ -203,7 +246,7 @@ recognize ``Required[]`` and ``NotRequired[]``:
 
 
 Interaction with ``__required_keys__`` and ``__optional_keys__``
-----------------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 An item marked with ``Required[]`` will always appear
 in the ``__required_keys__`` for its enclosing TypedDict. Similarly an item
@@ -226,6 +269,7 @@ How to Teach This
 
 To define a TypedDict where most keys are required and some are
 potentially-missing, define a single TypedDict as normal
+(without the ``total`` keyword)
 and mark those few keys that are potentially-missing with ``NotRequired[]``.
 
 To define a TypedDict where most keys are potentially-missing and a few are