Issue 18220: Expand itertools.islice docstring signature to 2 lines (original) (raw)
Created on 2013-06-15 06:29 by py.user, last changed 2022-04-11 14:57 by admin. This issue is now closed.
Messages (8)
Author: py.user (py.user) *
Date: 2013-06-15 06:29
http://docs.python.org/3/library/itertools.html#itertools.islice " itertools.islice(iterable, stop) itertools.islice(iterable, start, stop[, step])"
print(itertools.islice.doc) islice(iterable, [start,] stop [, step]) --> islice object ...
Author: py.user (py.user) *
Date: 2013-06-15 07:29
same thing with range(): http://docs.python.org/3/library/stdtypes.html?highlight=range#range http://docs.python.org/3//library/functions.html#func-range
and with slice(): http://docs.python.org/3/library/functions.html?highlight=slice#slice http://docs.python.org/3//library/functions.html#slice
can't patch them, because comma doesn't get into brackets "class range([start], stop[, step])"
Author: R. David Murray (r.david.murray) * 
Date: 2013-06-15 07:50
The documentation is correct, it is the docstrings that need to be changed.
Author: py.user (py.user) *
Date: 2013-06-17 06:54
range and slice are normal in python3.4
Author: A.M. Kuchling (akuchling) *
Date: 2013-06-21 11:33
This bug is entirely too cryptic. What exactly is the problem you're trying to fix?
Author: py.user (py.user) *
Date: 2013-06-21 17:31
[guest@localhost cpython]$ ./python Python 3.4.0a0 (default, Jun 22 2013, 04:24:17) [GCC 4.7.2 20121109 (Red Hat 4.7.2-8)] on linux Type "help", "copyright", "credits" or "license" for more information.
import itertools print(range.doc, slice.doc, itertools.islice.doc, sep='\n***\n')
range(stop) -> range object range(start, stop[, step]) -> range object
Returns a virtual sequence of numbers from start to stop by step.
slice(stop) slice(start, stop[, step])
Create a slice object. This is used for extended slicing (e.g. a[0:10:2]).
islice(iterable, [start,] stop [, step]) --> islice object
Return an iterator whose next() method returns selected values from an iterable. If start is specified, will skip all preceding elements; otherwise, start defaults to zero. Step defaults to one. If specified as another value, step determines how many values are skipped between successive calls. Works like a slice() on a list but returns an iterator.
I have updated the patch
Author: Terry J. Reedy (terry.reedy) *
Date: 2013-06-21 19:55
The problem with all of range, slice, and islice is that [start,] stop [, step] is an impossible signature and needed to be changed.
The actual signature is start_or_stop, [stop, [step]] with customized processing to interpret start_or_stop according to the presence of stop (which is not really optional). We suggestion to doc it this was rejected as equally confusing.
In 3.3, we decided to stop trying to force all signatures presented to the user into one line and instead use multiple lines to present what are multiple signatures from a user view. So this alternative was used for range and slice (and other functions).
For islice, the islice entry has itertools.islice(iterable, stop) itertools.islice(iterable, start, stop[, step])
Py.user is corrrect in suggesting the same change for islice docstring. I have changed the title to be clearer.
The itertools function table has islice() seq, [start,] stop [, step] elements from ...
I thing this should be changed also. A new line for arguments 'seq, stop' would say 'elements from seq[0:stop]' example 'islice('ABCDEFG', 2) --> A B Then remove brackets from [start] in the current line.
Py.user: To accept non-trival patches (typos, grammar corrections are trivial) we need a signed contributor agreement http://www.python.org/psf/contrib/ and http://www.python.org/psf/contrib/contrib-form/ new electronic form An '*' will appear after your name here when it is processed. I presume this will need a real (legal) name on the form, even though not in the tracker user list.
Author: Roundup Robot (python-dev) 
Date: 2013-06-22 23:26
New changeset 7ecca1a98220 by Andrew Kuchling in branch '3.3': Closes #18220: expand itertools.islice docstring to 2 lines http://hg.python.org/cpython/rev/7ecca1a98220
History
Date
User
Action
Args
2022-04-11 14:57:46
admin
set
github: 62420
2013-06-22 23:26:10
python-dev
set
status: open -> closed
nosy: + python-dev
messages: +
resolution: fixed
stage: patch review -> resolved
2013-06-21 19:55:52
terry.reedy
set
nosy: + terry.reedy
title: In itertools.islice() make prototype like in help() -> Expand itertools.islice docstring signature to 2 lines
messages: +
stage: patch review
2013-06-21 17:31:33
py.user
set
messages: +
2013-06-21 11:33:45
akuchling
set
nosy: + akuchling
messages: +
2013-06-17 06:54:55
py.user
set
messages: +
2013-06-17 06:53:08
py.user
set
files: + issue18220.patch
2013-06-17 06:52:51
py.user
set
files: - issue18220.patch
2013-06-15 07:50:34
r.david.murray
set
nosy: + r.david.murray
messages: +
2013-06-15 07:29:56
py.user
set
messages: +
2013-06-15 06:42:36
serhiy.storchaka
set
nosy: + rhettinger
2013-06-15 06:29:33
py.user
create