From 4540b8caa834fa52d2d98a9222325e580e5f16b5 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Mon, 29 Aug 2022 17:14:47 +0100 Subject: [PATCH 1/4] Docs: keywords in calls need not be identifiers We clarify that the keys of keyword arguments (necessarily given as a mapping) are acceptable in a call even if they would not be valid as the identifiers of formal parameters. --- Doc/reference/expressions.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 6bf21a7dde49a0..5c2450aa939c1b 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1054,10 +1054,20 @@ used in the same call, so in practice this confusion does not often arise. If the syntax ``**expression`` appears in the function call, ``expression`` must evaluate to a :term:`mapping`, the contents of which are treated as -additional keyword arguments. If a keyword is already present -(as an explicit keyword argument, or from another unpacking), +additional keyword arguments. If a parameter matching a key has already been +given a value (by an explicit keyword argument, or from another unpacking), a :exc:`TypeError` exception is raised. +When ``**expression`` is used, each key in this mapping must be +an instance of :class:`str` or a :term:`hashable` sub-class of it. +Each value from the mapping is assigned to the first formal parameter +eligible for keyword assignment, where the name is equal to the key. +A key need not be a Python identifier (e.g. ``"max-temp °F"`` is acceptable, +although it will not match any formal parameter that could be declared). +If there is no match to a formal parameter +the key-value pair is collected by the ``**`` parameter, if there is one, +or if there is not, a :exc:`TypeError` exception is raised. + Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be used as positional argument slots or as keyword argument names. From 2c0833d5683870de1bc6475f09e14642ad13241b Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Mon, 29 Aug 2022 23:45:15 +0100 Subject: [PATCH 2/4] Idiom "whose" in Doc/reference/expressions.rst Co-authored-by: Guido van Rossum --- Doc/reference/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 5c2450aa939c1b..6ee02725a77373 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1061,7 +1061,7 @@ a :exc:`TypeError` exception is raised. When ``**expression`` is used, each key in this mapping must be an instance of :class:`str` or a :term:`hashable` sub-class of it. Each value from the mapping is assigned to the first formal parameter -eligible for keyword assignment, where the name is equal to the key. +eligible for keyword assignment whose name is equal to the key. A key need not be a Python identifier (e.g. ``"max-temp °F"`` is acceptable, although it will not match any formal parameter that could be declared). If there is no match to a formal parameter From d939eb92936fe4f59086f0e81d71768ebb962cd7 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Tue, 30 Aug 2022 00:03:26 +0100 Subject: [PATCH 3/4] Simplify to "instance of str" in Doc/reference/expressions.rst Co-authored-by: Guido van Rossum --- Doc/reference/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 6ee02725a77373..1f208ff3389e0e 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1059,7 +1059,7 @@ given a value (by an explicit keyword argument, or from another unpacking), a :exc:`TypeError` exception is raised. When ``**expression`` is used, each key in this mapping must be -an instance of :class:`str` or a :term:`hashable` sub-class of it. +an instance of :class:`str`. Each value from the mapping is assigned to the first formal parameter eligible for keyword assignment whose name is equal to the key. A key need not be a Python identifier (e.g. ``"max-temp °F"`` is acceptable, From fd80c3a2c794a5576a44154580156b7c87514bbb Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Thu, 22 Sep 2022 11:07:13 -0700 Subject: [PATCH 4/4] "must be a string" instead of a `str` instance --- Doc/reference/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 1f208ff3389e0e..edba1c834a5a2b 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1059,7 +1059,7 @@ given a value (by an explicit keyword argument, or from another unpacking), a :exc:`TypeError` exception is raised. When ``**expression`` is used, each key in this mapping must be -an instance of :class:`str`. +a string. Each value from the mapping is assigned to the first formal parameter eligible for keyword assignment whose name is equal to the key. A key need not be a Python identifier (e.g. ``"max-temp °F"`` is acceptable,