classification
Title: Expand itertools.islice docstring signature to 2 lines
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: akuchling, docs@python, py.user, python-dev, r.david.murray, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2013-06-15 06:29 by py.user, last changed 2013-06-22 23:26 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue18220.patch py.user, 2013-06-17 06:53 review
Messages (8)
msg191199 - (view) 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
...
msg191200 - (view) 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])"
msg191201 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-06-15 07:50
The documentation is correct, it is the docstrings that need to be changed.
msg191316 - (view) Author: py.user (py.user) * Date: 2013-06-17 06:54
range and slice are normal in python3.4
msg191567 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2013-06-21 11:33
This bug is entirely too cryptic.  What exactly is the problem you're trying to fix?
msg191600 - (view) 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
msg191606 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) 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.
msg191680 - (view) Author: Roundup Robot (python-dev) (Python triager) 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
2013-06-22 23:26:10python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg191680

resolution: fixed
stage: patch review -> resolved
2013-06-21 19:55:52terry.reedysetnosy: + terry.reedy
title: In itertools.islice() make prototype like in help() -> Expand itertools.islice docstring signature to 2 lines
messages: + msg191606

stage: patch review
2013-06-21 17:31:33py.usersetmessages: + msg191600
2013-06-21 11:33:45akuchlingsetnosy: + akuchling
messages: + msg191567
2013-06-17 06:54:55py.usersetmessages: + msg191316
2013-06-17 06:53:08py.usersetfiles: + issue18220.patch
2013-06-17 06:52:51py.usersetfiles: - issue18220.patch
2013-06-15 07:50:34r.david.murraysetnosy: + r.david.murray
messages: + msg191201
2013-06-15 07:29:56py.usersetmessages: + msg191200
2013-06-15 06:42:36serhiy.storchakasetnosy: + rhettinger
2013-06-15 06:29:33py.usercreate