From dc3f97549a8fe4f7fea8d0326e394760b51caa6e Mon Sep 17 00:00:00 2001
From: Franek Magiera <framagie@gmail.com>
Date: Thu, 27 Apr 2023 00:39:39 +0200
Subject: [PATCH] gh-103629: Update typing.Unpack docs in compliance with PEP
 692 (#103894)

---
 Doc/library/typing.rst                        | 24 +++++++++++--
 Doc/whatsnew/3.12.rst                         | 34 +++++++++++++++++++
 ...-04-26-23-55-31.gh-issue-103629.-0reqn.rst |  2 ++
 3 files changed, 58 insertions(+), 2 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2023-04-26-23-55-31.gh-issue-103629.-0reqn.rst

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 15bab7775eadd8..409a95d528b5d3 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -98,6 +98,9 @@ annotations. These include:
     *Introducing* :data:`LiteralString`
 * :pep:`681`: Data Class Transforms
     *Introducing* the :func:`@dataclass_transform<dataclass_transform>` decorator
+* :pep:`692`: Using ``TypedDict`` for more precise ``**kwargs`` typing
+    *Introducing* a new way of typing ``**kwargs`` with :data:`Unpack` and
+    :data:`TypedDict`
 * :pep:`698`: Adding an override decorator to typing
     *Introducing* the :func:`@override<override>` decorator
 
@@ -1417,8 +1420,10 @@ These are not used in annotations. They are building blocks for creating generic
       tup: tuple[Unpack[Ts]]
 
    In fact, ``Unpack`` can be used interchangeably with ``*`` in the context
-   of types. You might see ``Unpack`` being used explicitly in older versions
-   of Python, where ``*`` couldn't be used in certain places::
+   of :class:`typing.TypeVarTuple <TypeVarTuple>` and
+   :class:`builtins.tuple <tuple>` types. You might see ``Unpack`` being used
+   explicitly in older versions of Python, where ``*`` couldn't be used in
+   certain places::
 
       # In older versions of Python, TypeVarTuple and Unpack
       # are located in the `typing_extensions` backports package.
@@ -1428,6 +1433,21 @@ These are not used in annotations. They are building blocks for creating generic
       tup: tuple[*Ts]         # Syntax error on Python <= 3.10!
       tup: tuple[Unpack[Ts]]  # Semantically equivalent, and backwards-compatible
 
+   ``Unpack`` can also be used along with :class:`typing.TypedDict` for typing
+   ``**kwargs`` in a function signature::
+
+      from typing import TypedDict, Unpack
+
+      class Movie(TypedDict):
+         name: str
+         year: int
+
+      # This function expects two keyword arguments - `name` of type `str`
+      # and `year` of type `int`.
+      def foo(**kwargs: Unpack[Movie]): ...
+
+   See :pep:`692` for more details on using ``Unpack`` for ``**kwargs`` typing.
+
    .. versionadded:: 3.11
 
 .. class:: ParamSpec(name, *, bound=None, covariant=False, contravariant=False)
diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 8fc95c493152e1..ff631ab54e16b7 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -66,6 +66,10 @@ Summary -- Release highlights
 
 .. PEP-sized items next.
 
+New typing features:
+
+* :ref:`whatsnew312-pep692`
+
 Important deprecations, removals or restrictions:
 
 * :pep:`623`, Remove wstr from Unicode
@@ -145,6 +149,36 @@ New Features
   In Python 3.14, the default will switch to ``'data'``.
   (Contributed by Petr Viktorin in :pep:`706`.)
 
+New Features Related to Type Hints
+==================================
+
+This section covers major changes affecting :pep:`484` type hints and
+the :mod:`typing` module.
+
+.. _whatsnew312-pep692:
+
+PEP 692: Using ``TypedDict`` for more precise ``**kwargs`` typing
+-----------------------------------------------------------------
+
+Typing ``**kwargs`` in a function signature as introduced by :pep:`484` allowed
+for valid annotations only in cases where all of the ``**kwargs`` were of the
+same type.
+
+This PEP specifies a more precise way of typing ``**kwargs`` by relying on
+typed dictionaries::
+
+   from typing import TypedDict, Unpack
+
+   class Movie(TypedDict):
+     name: str
+     year: int
+
+   def foo(**kwargs: Unpack[Movie]): ...
+
+See :pep:`692` for more details.
+
+(PEP written by Franek Magiera)
+
 
 Other Language Changes
 ======================
diff --git a/Misc/NEWS.d/next/Documentation/2023-04-26-23-55-31.gh-issue-103629.-0reqn.rst b/Misc/NEWS.d/next/Documentation/2023-04-26-23-55-31.gh-issue-103629.-0reqn.rst
new file mode 100644
index 00000000000000..6dc0a1cb5a3e4f
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2023-04-26-23-55-31.gh-issue-103629.-0reqn.rst
@@ -0,0 +1,2 @@
+Mention the new way of typing ``**kwargs`` with ``Unpack`` and ``TypedDict``
+introduced in :pep:`692`.