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.
diff --git a/Include/abstract.h b/Include/abstract.h
index 6ccda66..66b5fc5 100644
--- 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.
*/