[New-bugs-announce] [issue36644] Improve documentation of slice.indices()

[PEW's Corner]

New submission from PEW's Corner <pewscorner at gmail.com>:

The slice class is described in the Built-In Functions document:

https://docs.python.org/3/library/functions.html#slice

... but that entry fails to mention the indices() method, and states that slice objects "have no other explicit functionality" beyond the start, stop, and step attributes. The entry links only to a glossary item which doesn't provide more info.

However, it turns out that there is another description of slice objects - including the indices() method - in the Data model document:

https://docs.python.org/3/reference/datamodel.html#slice.indices

... but (as the rejected issue 11842 in my opinion correctly argues) this entry is not clear about how to interpret the return values from the indices() method, i.e. that they are appropriate as arguments to range() - not as arguments to a new slice().

So, right now the best documentation of the indices() method is the old Python 2.3 "what's new" documentation of extended slices:

https://docs.python.org/2.3/whatsnew/section-slices.html

"To simplify implementing sequences that support extended slicing, slice objects now have a method indices(length) which, given the length of a sequence, returns a (start, stop, step) tuple that can be passed directly to range(). indices() handles omitted and out-of-bounds indices in a manner consistent with regular slices (and this innocuous phrase hides a welter of confusing details!)."

I would propose to at least:
* Add a link from the slice class in the Built-In Functions doc to the slice object section of the Data model doc.
* Delete the statement about "no other explicit functionality" in the Built-In Functions doc.
* Mention in the Data model doc that the return values from indices() can be passed to range() to obtain the sequence of indices described by the slice when applied to a sequence object of the specified length, and perhaps make it clear that the indices() values do not in general represent the new start, stop, and step attributes of a truncated slice object.

----------
assignee: docs at python
components: Documentation
messages: 340364
nosy: docs at python, pewscorner
priority: normal
severity: normal
status: open
title: Improve documentation of slice.indices()
type: enhancement
versions: Python 3.7, Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue36644>
_______________________________________