From c96b26cb0639583731c78b7202ea2b8507ff1127 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 9 Aug 2022 08:22:54 -0700 Subject: [PATCH] GH-92678: Document that you shouldn't be doing your own dictionary offset calculations. (GH-95598) (GH-95821) Co-authored-by: Petr Viktorin Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> Co-authored-by: Mark Shannon --- Doc/c-api/object.rst | 18 ++++++++++++++++++ Doc/c-api/typeobj.rst | 17 +++++------------ Doc/whatsnew/3.11.rst | 4 ++++ Objects/object.c | 6 +++++- 4 files changed, 32 insertions(+), 13 deletions(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 07a625bac02fc4..fb03366056b0d2 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 e6df34e7db9551..47e1c8602197f7 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1709,18 +1709,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 3ea3fa63d408d6..a36564a8ab1905 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1549,6 +1549,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 d9fa779462a916..cb7853ca8cfd99 100644 --- a/Objects/object.c +++ b/Objects/object.c @@ -1086,7 +1086,11 @@ _PyObject_DictPointer(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) {