[docs] [issue28882] Slice confusing with negative stop and strides and the 0th element.

Terry J. Reedy report at bugs.python.org
Fri Dec 9 15:02:31 EST 2016

Terry J. Reedy added the comment:

Steven, your initial 'sentence' is missing something needed to make it a proper English sentence, and I cannot exactly guess what you meant.  But your later confusion is clear enough.

This tracker is for patching the Python docs and CPython code.  I believe the entry for the slice function/class, https://docs.python.org/3/library/functions.html#slice, could be improved.

First the word 'slice' is linked to the Glossary entry for 'slice'.  However, the latter is about subsequences, not about slice objects. It should instead link to the entry that contains the method description as https://docs.python.org/3/reference/datamodel.html#slice.indices.  (This is the target for the Index entry 'indices (slice method)'.  The 'slick objects' label needs to be made a target.

Second, the description "representing the set of indices specified by range(start, stop, step)" is only true when start and stop are valid non-negative indexes when applied to a particular sequence.  It is never true for negative values and not true when greater to or equal to the length of a particular sequence.  As the slice.indices entry says, 'Missing or out-of-bounds indices are handled in a manner consistent with regular slices."

In the example above, the issue is the negative stop, not the negative step.  Steven's problem was expecting the description to be true (whether or not he read it.)  It is worth noting, nowever, that reversed() was added because people had trouble using negative steps.  The following is much clearer than the corrected code above that the object is to separately reverse two haves of a list.

>>> n = 8
>>> a = range(8)
>>> [list(reversed(a[:n//2])), list(reversed(a[n//2:]))]
[[3, 2, 1, 0], [7, 6, 5, 4]]

As the Library Function entry hints, slice() is mainly intended for use internally and by 3rd-party extensions.

The description is even more wrong because the three arguments/attributes 'can have any type' (from the Data model slice object entry) whereas range arguments must be int-like.  (Allowing non-int-like arguments is for external extension use.)  In particular, slice(None) == slice(None, None) == slice(None, None, None) 'represents' all the indices of a particular sequence, in normal order, whereas None is not a valid argument for range().

I am not sure what replacement to propose.  I'd like to see if there is any previous discussion on the tracker.

A third and minor issue is that 'Numerical Python' should? be updated to "Numpy'.

assignee:  -> docs at python
components: +Documentation
nosy: +docs at python, terry.reedy
stage:  -> needs patch
title: RFC: Slice confusing with negative strides and the 0th element. -> Slice confusing with negative stop and strides and the 0th element.
type: behavior -> 
versions: +Python 3.6, Python 3.7

Python tracker <report at bugs.python.org>

More information about the docs mailing list