Applied remaining feedback

Some GH discussions are left opened for now, waiting for an answer.

Author: Viicos

peps/pep-9995.rst

@@ -5,7 +5,7 @@ Discussions-To:
 Status: Draft
 Type: Standards Track
 Topic: Typing
-Created: 23-Oct-2024
+Created: 25-Oct-2024
 Post-History:
 Python-Version: 3.14
 Resolution:
@@ -73,16 +73,17 @@ Rationale
 
 The new inlined syntax can be used to resolve these problems::
 
-    def get_movie() -> TypedDict[{'name': str, year: int, 'production': {'name': str, 'location': str}}]:
+    def get_movie() -> TypedDict[{'name': str, 'year': int, 'production': TypedDict[{'name': str, 'location': str}]}]:
         ...
 
 It is recommended to *only* make use of inlined typed dictionaries when the
-structured data isn't too large, as this can quickly get hard to read.
+structured data isn't too large, as this can quickly become hard to read.
 
 While less useful (as the functional or even the class-based syntax can be
-used), inlined typed dictionaries can be defined as a type alias::
+used), inlined typed dictionaries can be assigned to a variable, as an alias::
+
+    InlinedTD = TypedDict[{'name': str}]
 
-    type InlinedDict = TypedDict[{'name': str}]
 
 Specification
 =============
@@ -97,7 +98,43 @@ Inlined typed dictionaries can be referred as being *anonymous*, meaning they
 don't have a name. For this reason, their :attr:`~type.__name__` attribute
 will be set to an empty string.
 
-It is not possible to specify any class arguments such as ``total``.
+It is possible to define a nested inlined dictionary::
+
+    Movie = TypedDict[{'name': str, 'production': TypedDict[{'location': str}]}]
+
+    # Note that the following is invalid as per the updated `type_expression` production:
+    Movie = TypedDict[{'name': str, 'production': {'location': str}}]
+
+Although it is not possible to specify any class arguments such as ``total``,
+Any :external+typing:term:`type qualifier` can be used for individual fields::
+
+    Movie = TypedDict[{'name': NotRequired[str], 'year': ReadOnly[int]}]
+
+Inlined typed dictionaries are implicitly *total*, meaning all keys must be
+present. Using the :data:`~typing.Required` type qualifier is thus redundant.
+
+Type variables are allowed in inlined typed dictionaries, provided that they
+are bound to some outer scope::
+
+    class C[T]:
+        inlined_td: TypedDict[{'name': T}]  # OK, `T` is scoped to the class `C`.
+
+    reveal_type(C[int]().inlined_td['name'])  # Revealed type is 'int'
+
+
+    def fn[T](arg: T) -> TypedDict[{'name': T}]: ...  # OK: `T` is scoped to the function `fn`.
+
+    reveal_type(fn('a')['name'])  # Revealed type is 'str'
+
+
+    type InlinedTD[T] = TypedDict[{'name': T}]  # OK
+
+
+    T = TypeVar('T')
+
+    InlinedTD = TypedDict[{'name': T}]  # Not OK, `T` refers to a type variable that is not bound to any scope.
+
+**TODO** closed
 
 Runtime behavior
 ----------------
@@ -107,7 +144,7 @@ implemented as a function at runtime. To be made subscriptable, it will be
 changed to be a class.
 
 Creating an inlined typed dictionary results in a new class, so both syntaxes
-return the same type::
+return the same type (apart from the different :attr:`~type.__name__`)::
 
     from typing import TypedDict
 
@@ -117,12 +154,15 @@ return the same type::
 Typing specification changes
 ----------------------------
 
-The inlined typed dictionary syntax adds a new valid location for
-:term:`type expressions <typing:type expression>`. As such, the specification
-on :ref:`valid locations <typing:valid-types>` will need to be updated, most
-likely by adding a new item to the list:
+The inlined typed dictionary adds a new kind of
+:term:`type expressions <typing:type expression>`. As such, the
+:external+typing:token:`~expression-grammar:type_expression` production will
+need to be updated to include the inlined syntax:
 
-    * The definitions of the fields in the inlined typed dictionary syntax
+.. productionlist:: inlined-typed-dictionaries-grammar
+    new-type_expression: `~expression-grammar:type_expression`
+                       : | <TypedDict> '[' '{' (string: ':' `~expression-grammar:annotation_expression` ',')* '}' ']'
+                               (where string is any string literal)
 
 
 Backwards Compatibility
@@ -156,11 +196,9 @@ Mypy supports a similar syntax as an :option:`experimental feature <mypy:mypy.--
     def test_values() -> {"int": int, "str": str}:
         return {"int": 42, "str": "test"}
 
-Pyright has added support in version `1.1.297`_ (using :class:`dict`), but was later
-removed in version `1.1.366`_.
+Pyright added support for the new syntax in version `1.1.387`_.
 
-.. _1.1.297: https://github.com/microsoft/pyright/releases/tag/1.1.297
-.. _1.1.366: https://github.com/microsoft/pyright/releases/tag/1.1.366
+.. _1.1.387: https://github.com/microsoft/pyright/releases/tag/1.1.387
 
 Runtime implementation
 ----------------------
@@ -203,6 +241,24 @@ While this would avoid having to import :class:`~typing.TypedDict` from
 * If future work extends what inlined typed dictionaries can do, we don't have
   to worry about impact of sharing the symbol with :class:`dict`.
 
+Using a simple dictionary
+-------------------------
+
+Instead of subscripting the :class:`~typing.TypedDict` class, a plain
+dictionary could be used as an annotation::
+
+    def get_movie() -> {'title': str}: ...
+
+However, :pep:`584` added union operators on dictionaries and :pep:`604`
+introduced :ref:`union types <python:types-union>`. Both features make use of
+the :ref:`bitwise or (|) <python:bitwise>` operator, making the following use
+cases incompatible, especially for runtime introspection::
+
+    # Dictionaries are merged:
+    def fn() -> {'a': int} | {'b': str}: ...
+
+    # Raises a type error at runtime:
+    def fn() -> {'a': int} | int: ...
 
 Open Issues
 ===========
@@ -220,6 +276,24 @@ Should we allow the following?::
     class SubTD(InlinedTD):
         pass
 
+Using ``typing.Dict`` with a single argument
+--------------------------------------------
+
+While using :class:`dict` isn't ideal, we could make use of
+:class:`typing.Dict` with a single argument::
+
+    def get_movie() -> Dict[{'title': str}]: ...
+
+It is less verbose, doesn't have the baggage of :class:`dict`,
+and is defined as some kind of special form (an alias to the built-in
+``dict``).
+
+However, it is currently marked as deprecated (although not scheduled for
+removal), so it might be confusing to undeprecate it.
+
+This would also set a precedent on typing constructs being parametrizable
+with a different number of type arguments.
+
 
 Copyright
 =========