https://hg.python.org/cpython/rev/83e3c863594c changeset: 105398:83e3c863594c branch: 2.7 user: Martin Panter <vadmium+py@gmail.com> date: Wed Nov 30 10:32:40 2016 +0000 summary: Issue #25701: Document that some C APIs can both set and delete items Also document that using the dedicated functions to delete items is preferred. Using PyObject_SetAttr/String() and PySequence_SetItem/Slice() for deletion is deprecated. files: Doc/c-api/object.rst | 27 +++++++++++++++++++-------- Doc/c-api/sequence.rst | 12 ++++++++++-- Doc/c-api/typeobj.rst | 26 ++++++++++++++++---------- Include/abstract.h | 24 ++++++++++++------------ 4 files changed, 57 insertions(+), 32 deletions(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -55,25 +55,35 @@ .. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v) Set the value of the attribute named *attr_name*, for object *o*, to the value - *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement + *v*. Raise an exception and return ``-1`` on failure; + return ``0`` on success. This is the equivalent of the Python statement ``o.attr_name = v``. + If *v* is *NULL*, the attribute is deleted, however this feature is + deprecated in favour of using :c:func:`PyObject_DelAttr`. + .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v) Set the value of the attribute named *attr_name*, for object *o*, to the value - *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement + *v*. Raise an exception and return ``-1`` on failure; + return ``0`` on success. This is the equivalent of the Python statement ``o.attr_name = v``. + If *v* is *NULL*, the attribute is deleted, however this feature is + deprecated in favour of using :c:func:`PyObject_DelAttrString`. + .. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value) - Generic attribute setter function that is meant to be put into a type - object's ``tp_setattro`` slot. It looks for a data descriptor in the + Generic attribute setter and deleter function that is meant + to be put into a type object's :c:member:`~PyTypeObject.tp_setattro` + slot. It looks for a data descriptor in the dictionary of classes in the object's MRO, and if found it takes preference - over setting the attribute in the instance dictionary. Otherwise, the - attribute is set in the object's :attr:`~object.__dict__` (if present). - Otherwise, an :exc:`AttributeError` is raised and ``-1`` is returned. + over setting or deleting the attribute in the instance dictionary. Otherwise, the + attribute is set or deleted in the object's :attr:`~object.__dict__` (if present). + On success, ``0`` is returned, otherwise an :exc:`AttributeError` + is raised and ``-1`` is returned. .. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name) @@ -367,7 +377,8 @@ .. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v) - Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the + Map the object *key* to the value *v*. Raise an exception and + return ``-1`` on failure; return ``0`` on success. This is the equivalent of the Python statement ``o[key] = v``. diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -82,10 +82,14 @@ .. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v) - Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This + Assign object *v* to the *i*\ th element of *o*. Raise an exception + and return ``-1`` on failure; return ``0`` on success. This is the equivalent of the Python statement ``o[i] = v``. This function *does not* steal a reference to *v*. + If *v* is *NULL*, the element is deleted, however this feature is + deprecated in favour of using :c:func:`PySequence_DelItem`. + .. versionchanged:: 2.5 This function used an :c:type:`int` type for *i*. This might require changes in your code for properly supporting 64-bit systems. @@ -104,7 +108,11 @@ .. c:function:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v) Assign the sequence object *v* to the slice in sequence object *o* from *i1* to - *i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``. + *i2*. Raise an exception and return ``-1`` on failure; return ``0`` on success. + This is the equivalent of the Python statement ``o[i1:i2] = v``. + + If *v* is *NULL*, the slice is deleted, however this feature is + deprecated in favour of using :c:func:`PySequence_DelSlice`. .. versionchanged:: 2.5 This function used an :c:type:`int` type for *i1* and *i2*. This might diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -240,12 +240,13 @@ .. c:member:: setattrfunc PyTypeObject.tp_setattr - An optional pointer to the set-attribute-string function. + An optional pointer to the function for setting and deleting attributes. This field is deprecated. When it is defined, it should point to a function that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string instead of a Python string object to give the attribute name. The signature is - the same as for :c:func:`PyObject_SetAttrString`. + the same as for :c:func:`PyObject_SetAttrString`, but setting + *v* to *NULL* to delete an attribute must be supported. This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when @@ -389,9 +390,10 @@ .. c:member:: setattrofunc PyTypeObject.tp_setattro - An optional pointer to the set-attribute function. + An optional pointer to the function for setting and deleting attributes. - The signature is the same as for :c:func:`PyObject_SetAttr`. It is usually + The signature is the same as for :c:func:`PyObject_SetAttr`, but setting + *v* to *NULL* to delete an attribute must be supported. It is usually convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which implements the normal way of setting object attributes. @@ -831,7 +833,7 @@ typedef struct PyGetSetDef { char *name; /* attribute name */ getter get; /* C function to get the attribute */ - setter set; /* C function to set the attribute */ + setter set; /* C function to set or delete the attribute */ char *doc; /* optional doc string */ void *closure; /* optional additional data for getter and setter */ } PyGetSetDef; @@ -877,12 +879,14 @@ .. c:member:: descrsetfunc PyTypeObject.tp_descr_set - An optional pointer to a "descriptor set" function. + An optional pointer to a function for setting and deleting + a descriptor's value. The function signature is :: int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); + The *value* argument is set to *NULL* to delete the value. This field is inherited by subtypes. .. XXX explain. @@ -1263,9 +1267,11 @@ .. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript - This function is used by :c:func:`PyObject_SetItem` and has the same - signature. If this slot is *NULL*, the object does not support item - assignment. + This function is used by :c:func:`PyObject_SetItem` and + :c:func:`PyObject_DelItem`. It has the same signature as + :c:func:`PyObject_SetItem`, but *v* can also be set to *NULL* to delete + an item. If this slot is *NULL*, the object does not support item + assignment and deletion. .. _sequence-structs: @@ -1314,7 +1320,7 @@ This function is used by :c:func:`PySequence_SetItem` and has the same signature. This slot may be left to *NULL* if the object does not support - item assignment. + item assignment and deletion. .. c:member:: objobjproc PySequenceMethods.sq_contains diff --git a/Include/abstract.h b/Include/abstract.h --- a/Include/abstract.h +++ b/Include/abstract.h @@ -191,8 +191,8 @@ int PyObject_SetAttrString(PyObject *o, char *attr_name, PyObject *v); Set the value of the attribute named attr_name, for object o, - to the value, v. Returns -1 on failure. This is - the equivalent of the Python statement: o.attr_name=v. + to the value v. Raise an exception and return -1 on failure; return 0 on + success. This is the equivalent of the Python statement o.attr_name=v. */ @@ -201,8 +201,8 @@ int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v); Set the value of the attribute named attr_name, for object o, - to the value, v. Returns -1 on failure. This is - the equivalent of the Python statement: o.attr_name=v. + to the value v. Raise an exception and return -1 on failure; return 0 on + success. This is the equivalent of the Python statement o.attr_name=v. */ @@ -453,9 +453,9 @@ PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v); /* - Map the object, key, to the value, v. Returns - -1 on failure. This is the equivalent of the Python - statement: o[key]=v. + Map the object key to the value v. Raise an exception and return -1 + on failure; return 0 on success. This is the equivalent of the Python + statement o[key]=v. */ PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, char *key); @@ -1102,10 +1102,9 @@ PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v); /* - Assign object v to the ith element of o. Returns - -1 on failure. This is the equivalent of the Python - statement: o[i]=v. - + Assign object v to the ith element of o. Raise an exception and return + -1 on failure; return 0 on success. This is the equivalent of the + Python statement o[i]=v. */ PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i); @@ -1121,7 +1120,8 @@ /* Assign the sequence object, v, to the slice in sequence - object, o, from i1 to i2. Returns -1 on failure. This is the + object, o, from i1 to i2. Raise an exception and return + -1 on failure; return 0 on success. This is the equivalent of the Python statement: o[i1:i2]=v. */ -- Repository URL: https://hg.python.org/cpython