[Python-checkins] gh-96397: Document that keywords in calls need not be identifiers (#96393)

[gvanrossum]

https://github.com/python/cpython/commit/9d432b4a181cd42017699de4354e7b36c5b87d88
commit: 9d432b4a181cd42017699de4354e7b36c5b87d88
branch: main
author: Jeff Allen <ja.py at farowl.co.uk>
committer: gvanrossum <gvanrossum at gmail.com>
date: 2022-09-22T11:10:15-07:00
summary:

gh-96397: Document that keywords in calls need not be identifiers (#96393)

This represents the official SC stance, see
https://github.com/python/steering-council/issues/142#issuecomment-1252172695

files:
M Doc/reference/expressions.rst

diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 6bf21a7dde49..edba1c834a5a 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
+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,
+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.