Skip to content

bpo-38557: Improve documentation for list and tuple C API. #16925

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 26, 2019
Merged

bpo-38557: Improve documentation for list and tuple C API. #16925

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions Doc/c-api/list.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand Down Expand Up @@ -111,17 +112,16 @@ 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By itself, this is not obviously much of an improvement, but in the context of the earlier sentence for PyList_GetItem, "The position must be non-negative; indexing from the end of the list is not supported.", I think it is.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically, negative indices are supported. But they do not count from the end.



.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

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)
Expand Down
18 changes: 12 additions & 6 deletions Doc/c-api/tuple.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand Down
1 change: 1 addition & 0 deletions Doc/tools/susp-ignored.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down