gh-139852: Add PyObject_GetDict() function

Author: vstinner

Doc/c-api/object.rst

@@ -268,6 +268,8 @@ Object Protocol
    A generic implementation for the getter of a ``__dict__`` descriptor. It
    creates the dictionary if necessary.
 
+   Raise an :exc:`AttributeError` if the object has no ``__dict__``.
+
    This function may also be called to get the :py:attr:`~object.__dict__`
    of the object *o*. Pass ``NULL`` for *context* when calling it.
    Since this function may need to allocate memory for the
@@ -287,6 +289,27 @@ Object Protocol
    .. versionadded:: 3.3
 
 
+.. c:function:: int PyObject_GetDict(PyObject *obj, PyObject **dict)
+
+   Get a pointer to :py:attr:`~object.__dict__` of the object *obj*.
+
+   * If there is a ``__dict__``, set *\*dict* to a :term:`strong reference`
+     to the dictionary and return ``1``.
+   * If there is no ``__dict__``, set *\*dict* to ``NULL`` without setting
+     an exception and return ``0``.
+   * On error, set an exception and return ``-1``.
+
+   This function may need to allocate memory for the dictionary, so it may be
+   more efficient to call :c:func:`PyObject_GetAttr` when accessing an
+   attribute on the object.
+
+   .. versionadded:: next
+
+   .. seealso::
+      :c:func:`PyObject_GenericGetDict` and :c:func:`PyObject_GenericSetDict`
+      functions.
+
+
 .. c:function:: PyObject** _PyObject_GetDictPtr(PyObject *obj)
 
    Return a pointer to :py:attr:`~object.__dict__` of the object *obj*.
@@ -296,6 +319,9 @@ Object Protocol
    dictionary, so it may be more efficient to call :c:func:`PyObject_GetAttr`
    when accessing an attribute on the object.
 
+   .. deprecated:: 3.15
+      Use :c:func:`PyObject_GetDict` or :c:func:`PyObject_GetAttr` instead.
+
 
 .. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
 

Doc/whatsnew/3.15.rst

@@ -852,6 +852,10 @@ New features
 
   (Contributed by Victor Stinner in :gh:`129813`.)
 
+* Add :c:type:`PyObject_GetDict` function to get the
+  :py:attr:`~object.__dict__` of an object.
+  (Contributed by Victor Stinner in :gh:`139852`.)
+
 * Add :c:func:`PyTuple_FromArray` to create a :class:`tuple` from an array.
   (Contributed by Victor Stinner in :gh:`111489`.)
 
@@ -915,6 +919,10 @@ Deprecated C APIs
   since 3.15 and will be removed in 3.17.
   (Contributed by Nikita Sobolev in :gh:`136355`.)
 
+* Deprecate private :c:func:`_PyObject_GetDictPtr` function:
+  use public :c:func:`PyObject_GetDict` or :c:func:`PyObject_GetAttr` instead.
+  (Contributed by Victor Stinner in :gh:`139852`.)
+
 
 .. Add C API deprecations above alphabetically, not here at the end.
 

Include/cpython/object.h

@@ -299,7 +299,8 @@ PyAPI_FUNC(void) _PyObject_Dump(PyObject *);
 
 PyAPI_FUNC(PyObject*) _PyObject_GetAttrId(PyObject *, _Py_Identifier *);
 
-PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *);
+PyAPI_FUNC(int) PyObject_GetDict(PyObject *obj, PyObject **dict);
+Py_DEPRECATED(3.15) PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *);
 PyAPI_FUNC(void) PyObject_CallFinalizer(PyObject *);
 PyAPI_FUNC(int) PyObject_CallFinalizerFromDealloc(PyObject *);
 

Lib/test/test_capi/test_object.py

@@ -247,5 +247,50 @@ def func(x):
 
         func(object())
 
+    def test_object_getdict(self):
+        # Test PyObject_GetDict()
+        object_getdict = _testcapi.object_getdict
+
+        class MyClass:
+            pass
+        obj = MyClass()
+        obj.attr = 123
+
+        dict1 = object_getdict(obj)
+        dict2 = obj.__dict__
+        self.assertIs(dict1, dict2)
+
+        class NoDict:
+            __slots__ = ()
+        obj = NoDict()
+
+        self.assertEqual(object_getdict(obj), AttributeError)
+
+        # CRASHES object_getdict(NULL)
+
+    def test_object_genericgetdict(self):
+        # Test PyObject_GenericGetDict()
+        object_genericgetdict = _testcapi.object_genericgetdict
+
+        class MyClass:
+            pass
+        obj = MyClass()
+        obj.attr = 123
+
+        dict1 = object_genericgetdict(obj)
+        dict2 = obj.__dict__
+        self.assertIs(dict1, dict2)
+
+        class NoDict:
+            __slots__ = ()
+        obj = NoDict()
+
+        with self.assertRaisesRegex(AttributeError,
+                                    "This object has no __dict__"):
+            object_genericgetdict(obj)
+
+        # CRASHES object_genericgetdict(NULL)
+
+
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/C_API/2025-10-09-16-49-37.gh-issue-139852.76adZW.rst

@@ -0,0 +1,2 @@
+Add :c:type:`PyObject_GetDict` function to get the :py:attr:`~object.__dict__`
+of an object. Patch by Victor Stinner.

Misc/NEWS.d/next/C_API/2025-10-10-10-33-10.gh-issue-139852.SEDl82.rst

@@ -0,0 +1,2 @@
+Deprecate private :c:func:`_PyObject_GetDictPtr` function: use public
+:c:func:`PyObject_GetDict` or :c:func:`PyObject_GetAttr` instead.

Modules/_testcapi/object.c

@@ -485,6 +485,45 @@ is_uniquely_referenced(PyObject *self, PyObject *op)
 }
 
 
+static PyObject *
+object_getdict(PyObject *self, PyObject *obj)
+{
+    NULLABLE(obj);
+
+    PyObject *dict = UNINITIALIZED_PTR;
+    switch (PyObject_GetDict(obj, &dict)) {
+        case -1:
+            assert(dict == NULL);
+            return NULL;
+        case 0:
+            assert(dict == NULL);
+            return Py_NewRef(PyExc_AttributeError);
+        case 1:
+            return dict;
+        default:
+            Py_FatalError("PyObject_GetDict() returned invalid code");
+            Py_UNREACHABLE();
+    }
+}
+
+
+static PyObject *
+object_genericgetdict(PyObject *self, PyObject *obj)
+{
+    NULLABLE(obj);
+
+    PyObject *dict = PyObject_GenericGetDict(obj, NULL);
+    if (dict != NULL) {
+        return dict;
+    }
+
+    if (PyErr_Occurred()) {
+        return NULL;
+    }
+    return Py_NewRef(PyExc_AttributeError);
+}
+
+
 static PyMethodDef test_methods[] = {
     {"call_pyobject_print", call_pyobject_print, METH_VARARGS},
     {"pyobject_print_null", pyobject_print_null, METH_VARARGS},
@@ -511,6 +550,8 @@ static PyMethodDef test_methods[] = {
     {"test_py_is_funcs", test_py_is_funcs, METH_NOARGS},
     {"clear_managed_dict", clear_managed_dict, METH_O, NULL},
     {"is_uniquely_referenced", is_uniquely_referenced, METH_O},
+    {"object_getdict", object_getdict, METH_O},
+    {"object_genericgetdict", object_genericgetdict, METH_O},
     {NULL},
 };
 

Objects/object.c

@@ -1540,6 +1540,28 @@ _PyObject_ComputedDictPointer(PyObject *obj)
     return (PyObject **) ((char *)obj + dictoffset);
 }
 
+static int
+object_getdictptr(PyObject *obj, PyObject ***dict_ptr)
+{
+    if ((Py_TYPE(obj)->tp_flags & Py_TPFLAGS_MANAGED_DICT) == 0) {
+        *dict_ptr = _PyObject_ComputedDictPointer(obj);
+        return (*dict_ptr != NULL);
+    }
+
+    PyDictObject *dict = _PyObject_GetManagedDict(obj);
+    if (dict == NULL && Py_TYPE(obj)->tp_flags & Py_TPFLAGS_INLINE_VALUES) {
+        dict = _PyObject_MaterializeManagedDict(obj);
+        if (dict == NULL) {
+            *dict_ptr = NULL;
+            return -1;
+        }
+    }
+    *dict_ptr = (PyObject **)&_PyObject_ManagedDictPointer(obj)->dict;
+    assert(*dict_ptr != NULL);
+    return 1;
+}
+
+
 /* Helper to get a pointer to an object's __dict__ slot, if any.
  * Creates the dict from inline attributes if necessary.
  * Does not set an exception.
@@ -1550,20 +1572,31 @@ _PyObject_ComputedDictPointer(PyObject *obj)
 PyObject **
 _PyObject_GetDictPtr(PyObject *obj)
 {
-    if ((Py_TYPE(obj)->tp_flags & Py_TPFLAGS_MANAGED_DICT) == 0) {
-        return _PyObject_ComputedDictPointer(obj);
+    PyObject **dict_ptr;
+    if (object_getdictptr(obj, &dict_ptr) < 0) {
+        PyErr_Clear();
     }
-    PyDictObject *dict = _PyObject_GetManagedDict(obj);
-    if (dict == NULL && Py_TYPE(obj)->tp_flags & Py_TPFLAGS_INLINE_VALUES) {
-        dict = _PyObject_MaterializeManagedDict(obj);
-        if (dict == NULL) {
-            PyErr_Clear();
-            return NULL;
-        }
+    return dict_ptr;
+}
+
+
+int
+PyObject_GetDict(PyObject *obj, PyObject **dict)
+{
+    PyObject **dict_ptr;
+    int res = object_getdictptr(obj, &dict_ptr);
+    if (res == 1) {
+        assert(*dict_ptr != NULL);
+        *dict = Py_NewRef(*dict_ptr);
     }
-    return (PyObject **)&_PyObject_ManagedDictPointer(obj)->dict;
+    else {
+        assert(dict_ptr == NULL);
+        *dict = NULL;
+    }
+    return res;
 }
 
+
 PyObject *
 PyObject_SelfIter(PyObject *obj)
 {