SF bug #491415 PyDict_UpdateFromSeq2() unused

PyDict_UpdateFromSeq2():  removed it.
PyDict_MergeFromSeq2():  made it public and documented it.
PyDict_Merge() docs:  updated to reveal <wink> that the second
argument can be any mapping object.

Doc/api/concrete.tex

@@ -1817,22 +1817,45 @@ while (PyDict_Next(self->dict, &pos, &key, &value)) {
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override}
-  Iterate over dictionary \var{b} adding key-value pairs to dictionary
-  \var{a}.  If \var{override} is true, existing pairs in \var{a} will
+  Iterate over mapping object \var{b} adding key-value pairs to dictionary
+  \var{a}.
+  \var{b} may be a dictionary, or any object supporting
+  \function{PyMapping_Keys()} and \function{PyObject_GetItem()}.
+  If \var{override} is true, existing pairs in \var{a} will
   be replaced if a matching key is found in \var{b}, otherwise pairs
   will only be added if there is not a matching key in \var{a}.
-  Returns \code{0} on success or \code{-1} if an exception was
+  Return \code{0} on success or \code{-1} if an exception was
   raised.
 \versionadded{2.2}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b}
   This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C,
-  or \code{\var{a}.update(\var{b})} in Python.  Returns \code{0} on
+  or \code{\var{a}.update(\var{b})} in Python.  Return \code{0} on
   success or \code{-1} if an exception was raised.
   \versionadded{2.2}
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{int}{PyDict_MergeFromSeq2}{PyObject *a, PyObject *seq2,
+                                             int override}
+  Update or merge into dictionary \var{a}, from the key-value pairs in
+  \var{seq2}.  \var{seq2} must be an iterable object producing
+  iterable objects of length 2, viewed as key-value pairs.  In case of
+  duplicate keys, the last wins if \var{override} is true, else the
+  first wins.
+  Return \code{0} on success or \code{-1} if an exception
+  was raised.
+  Equivalent Python (except for the return value):
+
+\begin{verbatim}
+def PyDict_MergeFromSeq2(a, seq2, override):
+    for key, value in seq2:
+        if override or key not in a:
+            a[key] = value
+\end{verbatim}
+
+  \versionadded{2.2}
+\end{cfuncdesc}
 
 \section{Other Objects \label{otherObjects}}
 

Include/dictobject.h

@@ -97,9 +97,27 @@ extern DL_IMPORT(PyObject *) PyDict_Values(PyObject *mp);
 extern DL_IMPORT(PyObject *) PyDict_Items(PyObject *mp);
 extern DL_IMPORT(int) PyDict_Size(PyObject *mp);
 extern DL_IMPORT(PyObject *) PyDict_Copy(PyObject *mp);
-extern DL_IMPORT(int) PyDict_Update(PyObject *mp, PyObject *other);
-extern DL_IMPORT(int) PyDict_Merge(PyObject *mp, PyObject *other, int override);
 
+/* PyDict_Update(mp, other) is equivalent to PyDict_Merge(mp, other, 1). */
+extern DL_IMPORT(int) PyDict_Update(PyObject *mp, PyObject *other);
+
+/* PyDict_Merge updates/merges from a mapping object (an object that
+   supports PyMapping_Keys() and PyObject_GetItem()).  If override is true,
+   the last occurrence of a key wins, else the first.  The Python
+   dict.update(other) is equivalent to PyDict_Merge(dict, other, 1).
+*/
+extern DL_IMPORT(int) PyDict_Merge(PyObject *mp,
+				   PyObject *other,
+				   int override);
+
+/* PyDict_MergeFromSeq2 updates/merges from an iterable object producing
+   iterable objects of length 2.  If override is true, the last occurrence
+   of a key wins, else the first.  The Python dict constructor dict(seq2)
+   is equivalent to dict={}; PyDict_MergeFromSeq(dict, seq2, 1).
+*/
+extern DL_IMPORT(int) PyDict_MergeFromSeq2(PyObject *d,
+					   PyObject *seq2,
+					   int override);
 
 extern DL_IMPORT(PyObject *) PyDict_GetItemString(PyObject *dp, char *key);
 extern DL_IMPORT(int) PyDict_SetItemString(PyObject *dp, char *key, PyObject *item);

Misc/NEWS

@@ -75,8 +75,12 @@ Build
 
 C API
 
+- New function PyDict_MergeFromSeq2() exposes the builtin dict
+  constructor's logic for updating a dictionary from an iterable object
+  producing key-value pairs.
+
 - PyArg_ParseTupleAndKeywords() requires that the number of entries in
-  the keyword list equals the number of argument specifiers.  This
+  the keyword list equal the number of argument specifiers.  This
   wasn't checked correctly, and PyArg_ParseTupleAndKeywords could even
   dump core in some bad cases.  This has been repaired.  As a result,
   PyArg_ParseTupleAndKeywords may raise RuntimeError in bad cases that

Objects/dictobject.c

@@ -997,11 +997,11 @@ dict_update(PyObject *mp, PyObject *other)
 
    PyDict_{Update,Merge} update/merge from a mapping object.
 
-   PyDict_{Update,Merge}FromSeq2 update/merge from any iterable object
+   PyDict_MergeFromSeq2 updates/merges from any iterable object
    producing iterable objects of length 2.
 */
 
-static int
+int
 PyDict_MergeFromSeq2(PyObject *d, PyObject *seq2, int override)
 {
 	PyObject *it;	/* iter(seq2) */
@@ -1071,12 +1071,6 @@ Return:
 	return i;
 }
 
-static int
-PyDict_UpdateFromSeq2(PyObject *d, PyObject *seq2)
-{
-	return PyDict_MergeFromSeq2(d, seq2, 1);
-}
-
 int
 PyDict_Update(PyObject *a, PyObject *b)
 {