[Python-checkins] bpo-38557: Improve documentation for list and tuple C API. (GH-16925)
Serhiy Storchaka
webhook-mailer at python.org
Sat Oct 26 15:59:23 EDT 2019
https://github.com/python/cpython/commit/d898d20e8c228229eb68e545f544db13f246f216
commit: d898d20e8c228229eb68e545f544db13f246f216
branch: master
author: Serhiy Storchaka <storchaka at gmail.com>
committer: GitHub <noreply at github.com>
date: 2019-10-26T22:59:18+03:00
summary:
bpo-38557: Improve documentation for list and tuple C API. (GH-16925)
files:
M Doc/c-api/list.rst
M Doc/c-api/tuple.rst
M Doc/tools/susp-ignored.csv
diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst
index dc9026605be35..646f29d08a04b 100644
--- a/Doc/c-api/list.rst
+++ b/Doc/c-api/list.rst
@@ -71,8 +71,9 @@ List Objects
.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
- Set the item at index *index* in list to *item*. Return ``0`` on success
- or ``-1`` on failure.
+ Set the item at index *index* in list to *item*. Return ``0`` on success.
+ If *index* is out of bounds, return ``-1`` and set an :exc:`IndexError`
+ exception.
.. note::
@@ -111,8 +112,7 @@ List Objects
Return a list of the objects in *list* containing the objects *between* *low*
and *high*. Return *NULL* and set an exception if unsuccessful. Analogous
- to ``list[low:high]``. Negative indices, as when slicing from Python, are not
- supported.
+ to ``list[low:high]``. Indexing from the end of the list is not supported.
.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
@@ -120,8 +120,8 @@ List Objects
Set the slice of *list* between *low* and *high* to the contents of
*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
be *NULL*, indicating the assignment of an empty list (slice deletion).
- Return ``0`` on success, ``-1`` on failure. Negative indices, as when
- slicing from Python, are not supported.
+ Return ``0`` on success, ``-1`` on failure. Indexing from the end of the
+ list is not supported.
.. c:function:: int PyList_Sort(PyObject *list)
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 259ec4fb48515..a0d53e2030e63 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -57,7 +57,7 @@ Tuple Objects
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
- out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
+ out of bounds, return *NULL* and set an :exc:`IndexError` exception.
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
@@ -67,18 +67,21 @@ Tuple Objects
.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
- Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
- as a new tuple.
+ Return the slice of the tuple pointed to by *p* between *low* and *high*,
+ or *NULL* on failure. This is the equivalent of the Python expression
+ ``p[low:high]``. Indexing from the end of the list is not supported.
.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
Insert a reference to object *o* at position *pos* of the tuple pointed to by
- *p*. Return ``0`` on success.
+ *p*. Return ``0`` on success. If *pos* is out of bounds, return ``-1``
+ and set an :exc:`IndexError` exception.
.. note::
- This function "steals" a reference to *o*.
+ This function "steals" a reference to *o* and discards a reference to
+ an item already in the tuple at the affected position.
.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
@@ -88,7 +91,10 @@ Tuple Objects
.. note::
- This function "steals" a reference to *o*.
+ This macro "steals" a reference to *o*, and, unlike
+ :c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that
+ is being replaced; any reference in the tuple at position *pos* will be
+ leaked.
.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index 740850cae847c..fe15aae796fe6 100644
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -2,6 +2,7 @@ c-api/arg,,:ref,"PyArg_ParseTuple(args, ""O|O:ref"", &object, &callback)"
c-api/list,,:high,list[low:high]
c-api/sequence,,:i2,del o[i1:i2]
c-api/sequence,,:i2,o[i1:i2]
+c-api/tuple,,:high,p[low:high]
c-api/unicode,,:end,str[start:end]
c-api/unicode,,:start,unicode[start:start+length]
distutils/examples,267,`,This is the description of the ``foobar`` package.
More information about the Python-checkins
mailing list