gh-111262: Add PyDict_Pop() function (#112028)

_PyDict_Pop_KnownHash(): remove the default value and the return type
becomes an int.

Co-authored-by: Stefan Behnel <stefan_ml@behnel.de>
Co-authored-by: Antoine Pitrou <pitrou@free.fr>

2 files changed, 33 insertions, 0 deletions

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index 8ee3519..8471c98 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -173,6 +173,33 @@ Dictionary Objects
 
    .. versionadded:: 3.4
 
+
+.. c:function:: int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)
+
+   Remove *key* from dictionary *p* and optionally return the removed value.
+   Do not raise :exc:`KeyError` if the key missing.
+
+   - If the key is present, set *\*result* to a new reference to the removed
+     value if *result* is not ``NULL``, and return ``1``.
+   - If the key is missing, set *\*result* to ``NULL`` if *result* is not
+     ``NULL``, and return ``0``.
+   - On error, raise an exception and return ``-1``.
+
+   This is similar to :meth:`dict.pop`, but without the default value and
+   not raising :exc:`KeyError` if the key missing.
+
+   .. versionadded:: 3.13
+
+
+.. c:function:: int PyDict_PopString(PyObject *p, const char *key, PyObject **result)
+
+   Similar to :c:func:`PyDict_Pop`, but *key* is specified as a
+   :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
+   :c:expr:`PyObject*`.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: PyObject* PyDict_Items(PyObject *p)
 
    Return a :c:type:`PyListObject` containing all the items from the dictionary.
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 81e133b..136fe90 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -1175,6 +1175,12 @@ New Features
   Python ``list.extend()`` and ``list.clear()`` methods.
   (Contributed by Victor Stinner in :gh:`111138`.)
 
+* Add :c:func:`PyDict_Pop` and :c:func:`PyDict_PopString` functions: remove a
+  key from a dictionary and optionally return the removed value. This is
+  similar to :meth:`dict.pop`, but without the default value and not raising
+  :exc:`KeyError` if the key missing.
+  (Contributed by Stefan Behnel and Victor Stinner in :gh:`111262`.)
+
 
 Porting to Python 3.13
 ----------------------