New submission from PEW's Corner <pewscor...@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@python components: Documentation messages: 340364 nosy: docs@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 <rep...@bugs.python.org> <https://bugs.python.org/issue36644> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
