Skip to content

Commit bc8655c

Browse files
vstinnervstinner
committed
gh-106004: Add PyDict_GetItemRef() function
* Add PyDict_GetItemRef() and PyDict_GetItemStringRef() functions. * Add unit tests on the PyDict C API in test_capi.
1 parent a72683b commit bc8655c

File tree

10 files changed

+304
-14
lines changed

10 files changed

+304
-14
lines changed

‎Doc/c-api/dict.rst‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,10 +93,26 @@ Dictionary Objects
9393
Return ``0`` on success or ``-1`` on failure.
9494
9595
96+
.. c:function:: int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **pvalue)
97+
98+
Return a new :term:`strong reference` to the object from dictionary *p*
99+
which has a key *key*:
100+
101+
* If the key is present, set *\*pvalue* to a new :term:`strong reference`
102+
to the value and return ``1``.
103+
* If the key is missing, set *\*pvalue* to ``NULL`` and return ``0``.
104+
* On error, raise an exception and return ``-1``.
105+
106+
.. versionadded:: 3.13
107+
108+
See also the :c:func:`PyObject_GetItem` function.
109+
110+
96111
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
97112
98-
Return the object from dictionary *p* which has a key *key*. Return ``NULL``
99-
if the key *key* is not present, but *without* setting an exception.
113+
Return a :term:`borrowed reference` to the object from dictionary *p* which
114+
has a key *key*. Return ``NULL`` if the key *key* is missing *without*
115+
setting an exception.
100116
101117
Note that exceptions which occur while calling :meth:`__hash__` and
102118
:meth:`__eq__` methods will get suppressed.
@@ -126,6 +142,14 @@ Dictionary Objects
126142
To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
127143
128144
145+
.. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **pvalue)
146+
147+
Similar than :c:func:`PyDict_GetItemRef`, but *key* is specified as a
148+
:c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
149+
150+
.. versionadded:: 3.13
151+
152+
129153
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
130154
131155
This is the same as the Python-level :meth:`dict.setdefault`. If present, it

‎Doc/data/stable_abi.dat‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Doc/whatsnew/3.13.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -440,6 +440,13 @@ New Features
440440
``NULL`` if the referent is no longer live.
441441
(Contributed by Victor Stinner in :gh:`105927`.)
442442

443+
* Add :c:func:`PyDict_GetItemRef` and :c:func:`PyDict_GetItemStringRef`
444+
functions: similar than :c:func:`PyDict_GetItemWithError` but return a
445+
:term:`strong reference` instead of a :term:`borrowed reference`. Moreover,
446+
these functions return -1 on error and so checking ``PyErr_Occurred()`` is
447+
not needed.
448+
(Contributed by Victor Stinner in :gh:`106004`.)
449+
443450
Porting to Python 3.13
444451
----------------------
445452

‎Include/dictobject.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ PyAPI_DATA(PyTypeObject) PyDict_Type;
2121
PyAPI_FUNC(PyObject *) PyDict_New(void);
2222
PyAPI_FUNC(PyObject *) PyDict_GetItem(PyObject *mp, PyObject *key);
2323
PyAPI_FUNC(PyObject *) PyDict_GetItemWithError(PyObject *mp, PyObject *key);
24+
PyAPI_FUNC(int) PyDict_GetItemRef(PyObject *mp, PyObject *key, PyObject **pvalue);
2425
PyAPI_FUNC(int) PyDict_SetItem(PyObject *mp, PyObject *key, PyObject *item);
2526
PyAPI_FUNC(int) PyDict_DelItem(PyObject *mp, PyObject *key);
2627
PyAPI_FUNC(void) PyDict_Clear(PyObject *mp);
@@ -55,6 +56,7 @@ PyAPI_FUNC(int) PyDict_MergeFromSeq2(PyObject *d,
5556
int override);
5657

5758
PyAPI_FUNC(PyObject *) PyDict_GetItemString(PyObject *dp, const char *key);
59+
PyAPI_FUNC(int) PyDict_GetItemStringRef(PyObject *mp, const char *key, PyObject **pvalue);
5860
PyAPI_FUNC(int) PyDict_SetItemString(PyObject *dp, const char *key, PyObject *item);
5961
PyAPI_FUNC(int) PyDict_DelItemString(PyObject *dp, const char *key);
6062
#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000

‎Lib/test/test_stable_abi_ctypes.py‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Misc/NEWS.d/next/C API/2023-06-23-02-57-15.gh-issue-106004.-OToh6.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Add :c:func:`PyDict_GetItemRef` and :c:func:`PyDict_GetItemStringRef`
2+
functions: similar than :c:func:`PyDict_GetItemWithError` but return a
3+
:term:`strong reference` instead of a :term:`borrowed reference`. Patch by
4+
Victor Stinner.

‎Misc/stable_abi.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2432,3 +2432,7 @@
24322432
added = '3.13'
24332433
[function.PyWeakref_GetRef]
24342434
added = '3.13'
2435+
[function.PyDict_GetItemRef]
2436+
added = '3.13'
2437+
[function.PyDict_GetItemStringRef]
2438+
added = '3.13'

‎Modules/_testcapimodule.c‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3466,6 +3466,196 @@ test_weakref_capi(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
34663466
}
34673467

34683468

3469+
static PyObject *
3470+
test_dict_capi(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
3471+
{
3472+
assert(!PyErr_Occurred());
3473+
3474+
PyObject *dict= NULL, *key = NULL, *missing_key = NULL, *value = NULL;
3475+
PyObject *invalid_key = NULL;
3476+
int res;
3477+
3478+
// test PyDict_New()
3479+
dict = PyDict_New();
3480+
if (dict == NULL) {
3481+
goto error;
3482+
}
3483+
3484+
key = PyUnicode_FromString("key");
3485+
if (key == NULL) {
3486+
goto error;
3487+
}
3488+
3489+
missing_key = PyUnicode_FromString("missing_key");
3490+
if (missing_key == NULL) {
3491+
goto error;
3492+
}
3493+
3494+
value = PyUnicode_FromString("value");
3495+
if (value == NULL) {
3496+
goto error;
3497+
}
3498+
3499+
// test PyDict_SetItem()
3500+
Py_ssize_t key_refcnt = Py_REFCNT(key);
3501+
Py_ssize_t value_refcnt = Py_REFCNT(value);
3502+
res = PyDict_SetItem(dict, key, value);
3503+
if (res < 0) {
3504+
goto error;
3505+
}
3506+
assert(res == 0);
3507+
assert(Py_REFCNT(key) == (key_refcnt + 1));
3508+
assert(Py_REFCNT(value) == (value_refcnt + 1));
3509+
3510+
// test PyDict_SetItemString()
3511+
res = PyDict_SetItemString(dict, "key", value);
3512+
if (res < 0) {
3513+
goto error;
3514+
}
3515+
assert(res == 0);
3516+
assert(Py_REFCNT(key) == (key_refcnt + 1));
3517+
assert(Py_REFCNT(value) == (value_refcnt + 1));
3518+
3519+
// test PyDict_Size()
3520+
assert(PyDict_Size(dict) == 1);
3521+
3522+
// test PyDict_Contains(), key is present
3523+
assert(PyDict_Contains(dict, key) == 1);
3524+
3525+
// test PyDict_GetItem(), key is present
3526+
assert(PyDict_GetItem(dict, key) == value);
3527+
3528+
// test PyDict_GetItemString(), key is present
3529+
assert(PyDict_GetItemString(dict, "key") == value);
3530+
3531+
// test PyDict_GetItemWithError(), key is present
3532+
assert(PyDict_GetItemWithError(dict, key) == value);
3533+
assert(!PyErr_Occurred());
3534+
3535+
// test PyDict_GetItemRef(), key is present
3536+
PyObject *get_value = Py_Ellipsis; // marker value
3537+
assert(PyDict_GetItemRef(dict, key, &get_value) == 1);
3538+
assert(get_value == value);
3539+
Py_DECREF(get_value);
3540+
3541+
// test PyDict_GetItemStringRef(), key is present
3542+
get_value = Py_Ellipsis; // marker value
3543+
assert(PyDict_GetItemStringRef(dict, "key", &get_value) == 1);
3544+
assert(get_value == value);
3545+
Py_DECREF(get_value);
3546+
3547+
// test PyDict_Contains(), missing key
3548+
assert(PyDict_Contains(dict, missing_key) == 0);
3549+
3550+
// test PyDict_GetItem(), missing key
3551+
assert(PyDict_GetItem(dict, missing_key) == NULL);
3552+
assert(!PyErr_Occurred());
3553+
3554+
// test PyDict_GetItemString(), missing key
3555+
assert(PyDict_GetItemString(dict, "missing_key") == NULL);
3556+
assert(!PyErr_Occurred());
3557+
3558+
// test PyDict_GetItemWithError(), missing key
3559+
assert(PyDict_GetItem(dict, missing_key) == NULL);
3560+
assert(!PyErr_Occurred());
3561+
3562+
// test PyDict_GetItemRef(), missing key
3563+
get_value = Py_Ellipsis; // marker value
3564+
assert(PyDict_GetItemRef(dict, missing_key, &get_value) == 0);
3565+
assert(!PyErr_Occurred());
3566+
assert(get_value == NULL);
3567+
3568+
// test PyDict_GetItemStringRef(), missing key
3569+
get_value = Py_Ellipsis; // marker value
3570+
assert(PyDict_GetItemStringRef(dict, "missing_key", &get_value) == 0);
3571+
assert(!PyErr_Occurred());
3572+
assert(get_value == NULL);
3573+
3574+
// test PyDict_GetItem(), invalid dict
3575+
PyObject *invalid_dict = key; // borrowed reference
3576+
assert(PyDict_GetItem(invalid_dict, key) == NULL);
3577+
assert(!PyErr_Occurred());
3578+
3579+
// test PyDict_GetItemWithError(), invalid dict
3580+
assert(PyDict_GetItemWithError(invalid_dict, key) == NULL);
3581+
assert(PyErr_ExceptionMatches(PyExc_SystemError));
3582+
PyErr_Clear();
3583+
3584+
// test PyDict_GetItemRef(), invalid dict
3585+
get_value = Py_Ellipsis; // marker value
3586+
assert(PyDict_GetItemRef(invalid_dict, key, &get_value) == -1);
3587+
assert(PyErr_ExceptionMatches(PyExc_SystemError));
3588+
PyErr_Clear();
3589+
assert(get_value == NULL);
3590+
3591+
// test PyDict_GetItemStringRef(), invalid dict
3592+
get_value = Py_Ellipsis; // marker value
3593+
assert(PyDict_GetItemStringRef(invalid_dict, "key", &get_value) == -1);
3594+
assert(PyErr_ExceptionMatches(PyExc_SystemError));
3595+
PyErr_Clear();
3596+
assert(get_value == NULL);
3597+
3598+
invalid_key = PyList_New(0);
3599+
if (invalid_key == NULL) {
3600+
goto error;
3601+
}
3602+
3603+
// test PyDict_Contains(), invalid key
3604+
assert(PyDict_Contains(dict, invalid_key) == -1);
3605+
assert(PyErr_ExceptionMatches(PyExc_TypeError));
3606+
PyErr_Clear();
3607+
3608+
// test PyDict_GetItem(), invalid key
3609+
assert(PyDict_GetItem(dict, invalid_key) == NULL);
3610+
assert(!PyErr_Occurred());
3611+
3612+
// test PyDict_GetItemWithError(), invalid key
3613+
assert(PyDict_GetItemWithError(dict, invalid_key) == NULL);
3614+
assert(PyErr_ExceptionMatches(PyExc_TypeError));
3615+
PyErr_Clear();
3616+
3617+
// test PyDict_GetItemRef(), invalid key
3618+
get_value = Py_Ellipsis; // marker value
3619+
assert(PyDict_GetItemRef(dict, invalid_key, &get_value) == -1);
3620+
assert(PyErr_ExceptionMatches(PyExc_TypeError));
3621+
PyErr_Clear();
3622+
assert(get_value == NULL);
3623+
3624+
// test PyDict_DelItem(), key is present
3625+
assert(PyDict_DelItem(dict, key) == 0);
3626+
assert(PyDict_Size(dict) == 0);
3627+
3628+
// test PyDict_DelItem(), missing key
3629+
assert(PyDict_DelItem(dict, missing_key) == -1);
3630+
assert(PyErr_ExceptionMatches(PyExc_KeyError));
3631+
PyErr_Clear();
3632+
3633+
// test PyDict_DelItem(), invalid key
3634+
assert(PyDict_DelItem(dict, invalid_key) == -1);
3635+
assert(PyErr_ExceptionMatches(PyExc_TypeError));
3636+
PyErr_Clear();
3637+
3638+
// test PyDict_Clear()
3639+
PyDict_Clear(dict);
3640+
3641+
Py_DECREF(dict);
3642+
Py_DECREF(key);
3643+
Py_DECREF(missing_key);
3644+
Py_DECREF(value);
3645+
Py_DECREF(invalid_key);
3646+
3647+
Py_RETURN_NONE;
3648+
3649+
error:
3650+
Py_XDECREF(dict);
3651+
Py_XDECREF(key);
3652+
Py_XDECREF(missing_key);
3653+
Py_XDECREF(value);
3654+
Py_XDECREF(invalid_key);
3655+
return NULL;
3656+
}
3657+
3658+
34693659
static PyMethodDef TestMethods[] = {
34703660
{"set_errno", set_errno, METH_VARARGS},
34713661
{"test_config", test_config, METH_NOARGS},
@@ -3611,6 +3801,7 @@ static PyMethodDef TestMethods[] = {
36113801
{"test_atexit", test_atexit, METH_NOARGS},
36123802
{"check_pyimport_addmodule", check_pyimport_addmodule, METH_VARARGS},
36133803
{"test_weakref_capi", test_weakref_capi, METH_NOARGS},
3804+
{"test_dict_capi", test_dict_capi, METH_NOARGS},
36143805
{NULL, NULL} /* sentinel */
36153806
};
36163807

0 commit comments

Comments
 (0)