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".

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.

Ok, I agree.

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.
'''