# HG changeset patch
# Parent  ebec1a98ab81d19245e4bde2da03ccb489b9eb5f
Issue #25701: Document C API functions that both set and delete attributes

diff -r ebec1a98ab81 -r fa637d77516c 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 23 22:59:02 2015 +0000
@@ -67,25 +67,25 @@
 
 .. 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``). Returns ``-1`` on failure.
 
 
 .. 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``). Returns ``-1`` on failure.
 
 
 .. 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).
+   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).
    Otherwise, an :exc:`AttributeError` is raised and ``-1`` is returned.
 
 
diff -r ebec1a98ab81 -r fa637d77516c 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 23 22:59:02 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 ::
 
diff -r ebec1a98ab81 -r fa637d77516c Include/abstract.h
--- a/Include/abstract.h	Mon Nov 23 16:44:30 2015 +0200
+++ b/Include/abstract.h	Mon Nov 23 22:59:02 2015 +0000
@@ -191,9 +191,9 @@
 
      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). Returns -1 on failure.
 
        */
 
@@ -201,9 +201,9 @@
 
      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). Returns -1 on failure.
 
        */