PEP 590: update

Author: jdemeyer

pep-0590.rst

@@ -55,7 +55,7 @@ Calls are made through a function pointer taking the following parameters:
 * ``PyObject *callable``: The called object
 * ``Py_ssize_t n``: The number of arguments plus the optional flag ``PY_VECTORCALL_ARGUMENTS_OFFSET`` (see below)
 * ``PyObject *const *args``: A vector of arguments
-* ``PyTupleObject *kwnames``: A tuple of the names of the named arguments.
+* ``PyObject *kwnames``: Either ``NULL`` or a non-empty tuple of the names of the keyword arguments
 
 This is implemented by the function pointer type:
 ``typedef PyObject *(*vectorcallfunc)(PyObject *callable, Py_ssize_t n, PyObject *const *args, PyObject *kwnames);``
@@ -99,6 +99,8 @@ The call
 The call takes the form ``((vectorcallfunc)(((char *)o)+offset))(o, n, args, kwnames)`` where
 ``offset`` is ``Py_TYPE(o)->tp_vectorcall_offset``.
 The caller is responsible for creating the ``kwnames`` tuple and ensuring that there are no duplicates in it.
+For efficiently dealing with the common case of no keywords,
+``kwnames`` must be ``NULL`` if there are no keyword arguments.
 
 ``n`` is the number of postional arguments plus possibly the ``PY_VECTORCALL_ARGUMENTS_OFFSET`` flag.
 
@@ -131,8 +133,8 @@ The following functions or macros are added to the C API:
   Calls ``obj`` with the given arguments.
   Note that ``nargs`` may include the flag ``PY_VECTORCALL_ARGUMENTS_OFFSET``.
   The actual number of positional arguments is given by ``PyVectorcall_NARGS(nargs)``.
-  The argument ``keywords`` is a tuple of keyword names or ``NULL``.
-  An empty tuple has the same effect as passing ``NULL``.
+  The argument ``keywords`` is either a dict, a tuple of keyword names or ``NULL``.
+  An empty dict or empty tuple has the same effect as passing ``NULL``.
   This uses either the vectorcall protocol or ``tp_call`` internally;
   if neither is supported, an exception is raised.
 
@@ -149,7 +151,7 @@ New ``METH_VECTORCALL`` flag
 ----------------------------
 
 A new constant ``METH_VECTORCALL`` is added for specifying ``PyMethodDef`` structs.
-It means that the C function has the type ``PyObject *(*call) (PyObject *self, PyObject *const *args, Py_ssize_t nargs, PyObject *kwname)``.
+It means that the C function has the signature ``vectorcallfunc``.
 This should be the preferred flag for new functions, as this avoids a wrapper function.
 
 **NOTE**: the numerical value of ``METH_VECTORCALL`` is unspecified
@@ -205,7 +207,7 @@ The ``PyMethodDef`` protocol and Argument Clinic
 
 Argument Clinic [4]_ automatically generates wrapper functions around lower-level callables, providing safe unboxing of primitive types and
 other safety checks.
-Argument Clinic could be extended to generate wrapper objects conforming to the new ``vectorcall`` protocol.
+Argument Clinic could be extended to generate wrapper objects with the ``METH_VECTORCALL`` signature.
 This will allow execution to flow from the caller to the Argument Clinic generated wrapper and
 thence to the hand-written code with only a single indirection.