classification
Title: itertools.tee improve documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Alan.Cristhian, docs@python, rhettinger
Priority: low Keywords:

Created on 2013-10-29 22:55 by Alan.Cristhian, last changed 2019-08-22 23:15 by rhettinger. This issue is now closed.

Messages (4)
msg201693 - (view) Author: Alan Cristhian (Alan.Cristhian) Date: 2013-10-29 22:55
I had some problems using itertools.tee function. Fortunately I found the following advice on the PEP-323:

"Currently, the copied iterators remaintied to the original iterator. If the original advances, then so do all of the copies. Good practice is to overwrite the original So THAT anamolies do result: a, b = t (a)."

I believe that such advice should be in the documentation as well:

"Currently, the copied iterators remaintied to the original iterator. If the original advances, then so do all of the copies and vice versa. Good practice is to overwrite the original So THAT anamolies do result: a, b = t (a ). "

Note that I added "and vice versa".
msg202286 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-11-06 20:36
I don't want to recommend overwriting the variable name but will add a note for the rest:

"Copied iterators depend the original iterator. If the original advances, then so do the copies.  After teeing the iterators, the usual practice is
to stop working with the original iterator and operate only on the new tee-ed iterators."

FWIW, the situation is analogous to str.upper().  We note that string methods produce new strings.  We don't state that a best practice is to overwrite the variable with "s = s.upper()".  That is sometimes what you want and sometimes not.
msg202628 - (view) Author: Alan Cristhian (Alan.Cristhian) Date: 2013-11-11 14:20
Ok, I agree.
msg350240 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-22 23:15
This is out of date.  The docs currently have:

''' Once :func:`tee` has made a split, the original *iterable* should not be used anywhere else; otherwise, the *iterable* could get advanced without the tee objects being informed.
'''
History
Date User Action Args
2019-08-22 23:15:20rhettingersetstatus: open -> closed
resolution: out of date
messages: + msg350240

stage: resolved
2013-11-11 14:20:30Alan.Cristhiansetmessages: + msg202628
2013-11-06 20:36:15rhettingersetpriority: normal -> low

messages: + msg202286
2013-10-30 05:02:07rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
2013-10-29 22:55:33Alan.Cristhiancreate