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>

4 files changed, 32 insertions, 13 deletions

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 @@ Object Protocol
    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 @@ Object Protocol
    .. 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 @@ and :c:type:`PyType_Type` effectively act as defaults.)
    :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 @@ Changes in the Python API
   :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)
 {