gh-111262: Add PyDict_Pop() function [without default value nor KeyError]

[vstinner]

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

• Issue: Make _PyDict_Pop() public #111262

---

📚 Documentation preview 📚: https://cpython-previews--112028.org.readthedocs.build/

[vstinner]

This PR is based on PR gh-111939 (which was based on PR gh-111263). This API is different:

• Remove default_value parameter
• result argument can be NULL: it's common that the removed value is not used in the caller, see the PR
• Don't raise KeyError if the key is not present

[vstinner]

Simplified example where PyDict_Pop() is used to remove a dict key without caring of the removed value:

static int
sys_set_object(PyInterpreterState *interp, PyObject *key, PyObject *v)
{
    PyObject *sd = interp->sysdict;
    if (v == NULL) {
        if (PyDict_Pop(sd, key, NULL) < 0) {
            return -1;
        }
        // no need to care about KeyError or Py_DECREF()
        return 0;
    }
    else {
        return PyDict_SetItem(sd, key, v);
    }
}

Example which uses the removed value:

PyObject *ob;
if (PyDict_Pop(kwargs, key, &ob) < 0) {
    goto error;
}
if (ob != NULL) {
    result->ob_item[i] = ob;
}
else {
    // no need to care about KeyError or Py_DECREF()
    result->ob_item[i] = Py_NewRef(self->ob_item[i]);
}

[vstinner]

The function is not added to the limited C API: @encukou asks to wait until Python will have a C API Working Group.

[serhiy-storchaka]

This PR includes yet one change. It allows to pass NULL as a result address. It complicates the implementation, but makes the common use case simpler.

[serhiy-storchaka]

Why not remove it?

[vstinner]

I prefer to remove it in a separated PR: see #112026

[serhiy-storchaka]

Suggested change

	result = Py_NewRef(Py_None);
	return PyLong_FromLong(res);

[vstinner]

I prefer to return (0, None) to make the tests written in Python closer to what the C API returns. In test_capi.test_dict, you can see that as (0, NULL).

[serhiy-storchaka]

It can be confused with actual None. For example dict.get() return an actual none, but several corresponding C API functions return NULL.

In other tests I made them returning AttributeError or KeyError, as it is less chance to confuse with real value, but I think that it would be better to use a special singleton _testcapi.MISSING in future.

[vstinner]

As requested, I added PyDict_PopString() function.

I added tests on PyDict_PopString() and PyDict_Pop(dict, key, NULL).

I also addresssed @serhiy-storchaka's review.

[vstinner]

@serhiy-storchaka: I added more tests.

[serhiy-storchaka]

LGTM.

What interface do you prefer, Victor? This or #111939? I am ready to make a review of #111939 if you add corresponding *String variant and tests.

[scoder]

LGTM overall, just wording fixes.

[scoder]

It's usually clearer to write "not raising an exception" (at all) than naming an explicit exception and leaving it open whether other exceptions might be raised in the described case.

Suggested change

	* 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 the
	similar to :meth:`dict.pop`, but without the default value and do not raise
	:exc:`KeyError` if the key missing.
	* 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
	an exception if the key missing.

[vstinner]

Thanks. I applied your suggestion to the 3 places where I wrote that doc, but I kept KeyError. IMO it's useful to be explicit about KeyError to understand what we are talking about.

[vstinner]

@serhiy-storchaka:

What interface do you prefer, Victor?

At the beginning, I had no idea. It was very blurry. What helped me to make my own opinion was to actually use the different proposed API and look at the updated code. I really like this API without the default value: I'm convinced by these examples.

In short, I prefer this PR.