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/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst
index 653f9ad..d82a7b0 100644
--- 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