Reviewers: haypo, vadmium, http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst File Doc/c-api/object.rst (right): http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst#newcode7... Doc/c-api/object.rst:71: object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``), May be refer to PyObject_DelAttr if v is NULL? http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst#newcode7... Doc/c-api/object.rst:72: otherwise set it to *v* (``o.attr_name = v``). Raises an exception and It looks to me that "Return" and "Raise" are more preferable to "Returns" and "Raises" in the documentation. Please review this at http://bugs.python.org/review/25701/ Affected files: Doc/c-api/object.rst Doc/c-api/sequence.rst Doc/c-api/typeobj.rst Include/abstract.h # HG changeset patch # Parent ebec1a98ab81d19245e4bde2da03ccb489b9eb5f Issue #25701: Document C API functions that both set and delete objects diff -r ebec1a98ab81 Doc/c-api/object.rst --- a/Doc/c-api/object.rst Mon Nov 23 16:44:30 2015 +0200 +++ b/Doc/c-api/object.rst Mon Nov 30 05:38:20 2015 +0000 @@ -67,26 +67,29 @@ .. 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 - ``o.attr_name = v``. + Set or delete the value of the attribute named *attr_name*, for + object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``), + otherwise set it to *v* (``o.attr_name = v``). Raises an exception and + returns ``-1`` on failure; returns ``0`` on success. .. 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 - ``o.attr_name = v``. + Set or delete the value of the attribute named *attr_name*, for + object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``), + otherwise set it to *v* (``o.attr_name = v``). Raises an exception and + returns ``-1`` on failure; returns ``0`` on success. .. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value) - Generic attribute setter function that is meant to be put into a type + Generic attribute setter and deleter function that is meant to be put into a type object's ``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) @@ -378,7 +381,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*. Raises an exception and + returns ``-1`` on failure; returns ``0`` on success. This is the equivalent of the Python statement ``o[key] = v``. diff -r ebec1a98ab81 Doc/c-api/sequence.rst --- a/Doc/c-api/sequence.rst Mon Nov 23 16:44:30 2015 +0200 +++ b/Doc/c-api/sequence.rst Mon Nov 30 05:38:20 2015 +0000 @@ -62,8 +62,10 @@ .. 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 - is the equivalent of the Python statement ``o[i] = v``. This function *does + Assign object *v* to the *i*\ th element of *o*, or delete the + element if *v* is *NULL*. Raises an exception and returns ``-1`` on + failure; returns ``0`` on success. This is the equivalent of the + Python statements ``o[i] = v`` and ``del o[i]``. This function *does not* steal a reference to *v*. diff -r ebec1a98ab81 Doc/c-api/typeobj.rst --- a/Doc/c-api/typeobj.rst Mon Nov 23 16:44:30 2015 +0200 +++ b/Doc/c-api/typeobj.rst Mon Nov 30 05:38:20 2015 +0000 @@ -208,7 +208,7 @@ .. 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 @@ -351,7 +351,7 @@ .. 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 convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which @@ -724,7 +724,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; @@ -775,7 +775,8 @@ .. 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 :: @@ -1171,9 +1172,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: @@ -1222,7 +1225,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 -r ebec1a98ab81 Include/abstract.h --- a/Include/abstract.h Mon Nov 23 16:44:30 2015 +0200 +++ b/Include/abstract.h Mon Nov 30 05:38:20 2015 +0000 @@ -191,9 +191,10 @@ 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: o.attr_name=v. + Set or delete the value of the attribute named attr_name, for object o. + If v is NULL, delete the value (del o.attr_name), otherwise set it to v + (o.attr_name=v). Raises an exception and returns -1 on failure; returns + 0 on success. */ @@ -201,9 +202,10 @@ 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. + Set or delete the value of the attribute named attr_name, for object o. + If v is NULL, delete the value (del o.attr_name), otherwise set it to v + (o.attr_name=v). Raises an exception and returns -1 on failure; returns + 0 on success. */ @@ -993,9 +995,10 @@ 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, or delete the element if v is + NULL. Raises an exception and returns -1 on failure; returns 0 on + success. This is the equivalent of the Python statements: "o[i]=v" and + "del o[i]". */ PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);