GH-92678: Document that you shouldn't be doing your own dictionary offset calculations. (GH-95598)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 07a625b..fb03366 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -126,6 +126,14 @@
A generic implementation for the getter of a ``__dict__`` descriptor. It
creates the dictionary if necessary.
+ 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
+ dictionary, it may be more efficient to call :c:func:`PyObject_GetAttr`
+ when accessing an attribute on the object.
+
+ On failure, returns ``NULL`` with an exception set.
+
.. versionadded:: 3.3
@@ -137,6 +145,16 @@
.. versionadded:: 3.3
+.. c:function:: PyObject** _PyObject_GetDictPtr(PyObject *obj)
+
+ Return a pointer to :py:attr:`~object.__dict__` of the object *obj*.
+ If there is no ``__dict__``, return ``NULL`` without setting an exception.
+
+ 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.
+
+
.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 3af48f4..b8baa7c 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1715,18 +1715,11 @@
:c:member:`~PyTypeObject.tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
at the very end of the structure.
- The real dictionary offset in an instance can be computed from a negative
- :c:member:`~PyTypeObject.tp_dictoffset` as follows::
-
- dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
- if dictoffset is not aligned on sizeof(void*):
- round up to sizeof(void*)
-
- where :c:member:`~PyTypeObject.tp_basicsize`, :c:member:`~PyTypeObject.tp_itemsize` and :c:member:`~PyTypeObject.tp_dictoffset` are
- taken from the type object, and :attr:`ob_size` is taken from the instance. The
- absolute value is taken because ints use the sign of :attr:`ob_size` to
- store the sign of the number. (There's never a need to do this calculation
- yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.)
+ The :c:member:`~PyTypeObject.tp_dictoffset` should be regarded as write-only.
+ To get the pointer to the dictionary call :c:func:`PyObject_GenericGetDict`.
+ Calling :c:func:`PyObject_GenericGetDict` may need to allocate memory for the
+ dictionary, so it is may be more efficient to call :c:func:`PyObject_GetAttr`
+ when accessing an attribute on the object.
**Inheritance:**
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index 88f62bc..39f1dab 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -1544,6 +1544,10 @@
:func:`compile` and other related functions. If invalid positions are detected,
a :exc:`ValueError` will be raised. (Contributed by Pablo Galindo in :gh:`93351`)
+* :c:member:`~PyTypeObject.tp_dictoffset` should be treated as write-only.
+ It can be set to describe C extension clases to the VM, but should be regarded
+ as meaningless when read. To get the pointer to the object's dictionary call
+ :c:func:`PyObject_GenericGetDict` instead.
Build Changes
=============
diff --git a/Objects/object.c b/Objects/object.c
index f0c0434..a90c6fa 100644
--- a/Objects/object.c
+++ b/Objects/object.c
@@ -1079,7 +1079,11 @@ _PyObject_ComputedDictPointer(PyObject *obj)
/* 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. */
+ * Does not set an exception.
+ *
+ * Note that the tp_dictoffset docs used to recommend this function,
+ * so it should be treated as part of the public API.
+ */
PyObject **
_PyObject_GetDictPtr(PyObject *obj)
{
