[Python-checkins] GH-92678: Document that you shouldn't be doing your own dictionary offset calculations. (GH-95598)
markshannon
webhook-mailer at python.org
Tue Aug 9 09:27:00 EDT 2022
https://github.com/python/cpython/commit/8d37c62c2a2579ae7839ecaf8351e862f2ecc9bb
commit: 8d37c62c2a2579ae7839ecaf8351e862f2ecc9bb
branch: main
author: Mark Shannon <mark at hotpy.org>
committer: markshannon <mark at hotpy.org>
date: 2022-08-09T14:26:37+01:00
summary:
GH-92678: Document that you shouldn't be doing your own dictionary offset calculations. (GH-95598)
Co-authored-by: Petr Viktorin <encukou at gmail.com>
Co-authored-by: Stanley <46876382+slateny at users.noreply.github.com>
files:
M Doc/c-api/object.rst
M Doc/c-api/typeobj.rst
M Doc/whatsnew/3.11.rst
M Objects/object.c
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 07a625bac02f..fb03366056b0 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 3af48f408ea3..b8baa7c7dc39 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 88f62bc2d91b..39f1dab590a9 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 f0c0434fab3d..a90c6faf99db 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)
{
More information about the Python-checkins
mailing list