itertools.permutations docstring is misleading

[devdanzin]

BPO	2536
Nosy	@birkenfeld, @rhettinger, @devdanzin

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2008-06-10.12:48:35.753>
created_at = <Date 2008-04-02.10:48:02.519>
labels = ['type-bug', 'library']
title = 'itertools.permutations docstring is misleading'
updated_at = <Date 2008-06-10.12:48:35.652>
user = 'https://github.com/devdanzin'

bugs.python.org fields:

activity = <Date 2008-06-10.12:48:35.652>
actor = 'georg.brandl'
assignee = 'none'
closed = True
closed_date = <Date 2008-06-10.12:48:35.753>
closer = 'georg.brandl'
components = ['Library (Lib)']
creation = <Date 2008-04-02.10:48:02.519>
creator = 'ajaksu2'
dependencies = []
files = []
hgrepos = []
issue_num = 2536
keywords = []
message_count = 2.0
messages = ['64846', '67902']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'rhettinger', 'ajaksu2']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue2536'
versions = ['Python 2.6']

[devdanzin]

Currently, Modules/itertoolsmodule.c lines 2471-2475 are:

PyDoc_STRVAR(permutations_doc,
"permutations(iterables[, r]) --> permutations object\n\
\n\
Return successive r-length permutations of elements in the iterable.\n\n\
permutations(range(4), 3) --> (0,1,2), (0,1,3), (0,2,3), (1,2,3)");

but that describes behavior of itertools.combinations. The correct
example is in a comment on line 2254 of the same file:

'permutations(range(3), 2) --> (0,1) (0,2) (1,0) (1,2) (2,0) (2,1)'

I used "misleading" instead of "wrong" because the current docstring
does show a subset of the real output and could be said to be
incomplete. If that is the case, I suggest being explicit:

'permutations(range(4), 3) --> (0, 1, 2), (0, 1, 3), (0, 2, 1), (0, 2,
3), (0, 3, 1), (0, 3, 2), (1, 0, 2), (1, 0, 3), (1, 2, 0), (1, 2, 3),
(1, 3, 0), (1, 3, 2), (2, 0, 1), (2, 0, 3), (2, 1, 0), (2, 1, 3), (2, 3,
0), (2, 3, 1), (3, 0, 1), (3, 0, 2), (3, 1, 0), (3, 1, 2), (3, 2, 0),
(3, 2, 1)'

[birkenfeld]

Fixed in r64067.