Title: Make chain.from_iterable an alias for a new chain_iterable.
Type: enhancement Stage: needs patch
Components: Versions: Python 3.4
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: eric.araujo, eric.smith, python-dev, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2013-08-15 21:05 by terry.reedy, last changed 2013-09-09 07:10 by rhettinger. This issue is now closed.

Messages (4)
msg195290 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-08-15 21:05
It has become apparent from various discussions in recent months that chain.from_iterable is at least as useful as chain. In fact, I now think that 'chain' should have been what chain.from_iterable is, with current chain(a,b,c) done as chain((a,b,d)). But too late for that.

Based on today's pydev post* by Eric Smith, I propose that chain_iterable (or chain_from_iterable, but I think the 'from' is not needed) be added to itertools and listed in the index table and documented as a function in its own right. 

This would make the long discussion of how to properly document chain.from_iterable (#18301) moot, as the method could be simply mentioned as a (deprecated) alias of chain_iterable.

* "I think that [itertools.chain.from_iterable] was a mistake, too. As a
recent discussion showed, it's not exactly discoverable. The fact that
it's not mentioned in the list of functions at the top of the
documentation doesn't help. And "chain" is documented as a "module
function", and "chain.from_iterable" as a "classmethod" making it all
the more confusing.

I think itertools.combinations and itertools.combinations_with_replacement is the better example of related
functions that should be followed. Not nested, no special parameters
trying to differentiate them: just two different function names."

If this proposal is rejected, then chain.iterable should be added to the index table. That would make it more discoverable, but not less confusing.
msg197348 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-09-09 06:16
I'll work on improving the docs to make this classmethod more discoverable in docs, but the API is going to stay the same.
msg197349 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-09-09 06:30
New changeset fa1fa88b685b by Raymond Hettinger in branch 'default':
Issue 18752:  Make chain.from_iterable() more visible in the documentation.
msg197353 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-09-09 07:02
New changeset 23f77dc58979 by Raymond Hettinger in branch '3.3':
Issue 18752:  Make chain.from_iterable() more visible in the documentation.
Date User Action Args
2013-09-09 07:10:18rhettingersetstatus: open -> closed
2013-09-09 07:02:19python-devsetmessages: + msg197353
2013-09-09 06:30:14python-devsetnosy: + python-dev
messages: + msg197349
2013-09-09 06:16:04rhettingersetresolution: rejected
messages: + msg197348
2013-09-09 03:17:22eric.araujosetnosy: + eric.araujo
2013-09-01 06:30:04rhettingersetassignee: rhettinger
2013-08-15 21:05:59terry.reedycreate