Shorten the Intended Usage section and further refactor the Motivatio…

…n section
python · gvanrossum · Aug 23, 2022 · Jul 24, 2022 · Jul 25, 2022 · Jul 25, 2022
commit 52d151b6366c20f762aac1513ba9faec8e66d7ce
@@ -22,8 +22,9 @@ be very limiting. Therefore, in this PEP we propose a new way to enable more
 precise ``**kwargs`` typing. The new approach revolves around using
 ``TypedDict`` to type ``**kwargs`` that comprise keyword arguments of different
 types. It also involves introducing a grammar change and a new dunder
-``__typing_kwargs_unpack__``. The scope of a new dunder is expected to cover
-the ``TypedDict`` type only.
+``__typing_kwargs_unpack__``.
+
+.. _pep-692-motivation:
 
 Motivation
 ==========
@@ -49,12 +50,9 @@ cases when there is a top-level function that is a part of a public API and it
 calls a bunch of helper functions, all of which expect the same keyword
 arguments. Unfortunately, if those helper functions were to use ``**kwargs``,
 there is no way to properly type hint them if the keyword arguments they expect
-are of different types. However, even if the keyword arguments are of the same
-type, there is no way to check if the function is being called with keyword
-names that it actually expects. All of this makes certain issues difficult to
-spot. For example, a helper function could be updated to take account of a new
-keyword argument, but the public function which uses the helper may not have it
-in its signature.
+are of different types. In addition, even if the keyword arguments are of the
+same type, there is no way to check whether the function is being called with
+keyword names that it actually expects.
 
 As described in the :ref:`Intended Usage <pep-692-intended-usage>` section,
 using ``**kwargs`` is not always the best tool for the job. Despite that, it is
@@ -376,32 +374,15 @@ to perform the function call::
 
 Intended Usage
 --------------
-
-This proposal will bring a large benefit to the codebases that already use
-``**kwargs`` because of the flexibility that they provided in the initial
-phases of the development, but now are mature enough to use a stricter
-contract via type hints. 
-
-Adding type hints directly in the source code as opposed to the ``*.pyi``
-stubs benefits anyone who reads the code as it is easier to understand. Given
-that currently precise ``**kwargs`` type hinting is impossible in that case the
-choices are to either not type hint ``**kwargs`` at all, which isn't ideal, or
-to refactor the function to use explicit keyword arguments, which often exceeds
-the scope of time and effort allocated to adding type hinting and, as any code
-change, introduces risk for both project maintainers and users. In that case
-hinting ``**kwargs`` using a ``TypedDict`` as described in this PEP will not
-require refactoring and function body and function invocations could be
-appropriately type checked.
-
-Moreover, using ``**kwargs`` with more precise type hinting would allow for
-less code and less copy pasting in cases when a module contains a bunch of
-functions that expect similar keyword arguments. Using ``**kwargs`` with a
-``TypedDict`` as propsed in this PEP is much more concise than explicitly
-repeating the keyword arguments every time. 
-
-Another useful pattern that justifies using and typing ``**kwargs`` as proposed
-is when the function's API should allow for optional keyword arguments that
-don't have default values.
+The intended use cases for this proposal are described in the :ref:`Motivation
+<pep-692-motivation>` section. In summary, more precise ``**kwargs`` typing
+can bring benefits to already existing codebases that used ``**kwargs``
+initially, but now are mature enough to use a stricter contract via type hints.
+Using ``**kwargs`` can also help in reducing code duplication and the amount of
+copy-pasting needed when there is a bunch of functions that require the same
+set of keyword arguments. Finally, ``**kwargs`` are useful for cases when a
+function needs to facilitate optional keyword arguments that don't have obvious
+default values.
 
 However, it has to be pointed out that in some cases there are better tools
 for the job than using ``TypedDict`` to type ``**kwargs`` as proposed in this