Note change in behavior for itertools.tee() with "flattening" itertables

[treyhunner]

As of Python 3.13, itertools.tee() now "flattens" other tee objects, as documented in #123885.

This behavior change seems to be from Python 3.13 because tee() objects in Python 3.12 and below do not seem to flatten.

It seems like this behavior should have a "Changed in version 3.13" call out in the documentation for `itertools.tee.

A student just ran across this change in behavior and found it confusing. I did some experimenting on different Python versions and some research and eventually discovered this new flattening behavior. A call-out in the documentation might have saved us some time.

Linked PRs

• gh-137597: Clarify flattening and bugfix for itertools.tee #137599

[pochmann3]

It was flattening before that already. What's the code you tried? There was a bug with the first iterator that got fixed. Is that the change you observed?

[pochmann3]

Here's a test of the flattening, with Python 3.7. The deeply "nested" tees are fast, thanks to the flattening. And for comparison, the deeply nested chains are slow, because they don't flatten.

from itertools import tee, chain
from time import time
import sys

n = 10**4

a, b = tee([1] * n)
for _ in range(n):
    a, b = tee(a)
t0 = time()
print(sum(a), sum(b), time() - t0)

a, b = tee([1] * n)
for _ in range(n):
    a, b = tee(b)
t0 = time()
print(sum(a), sum(b), time() - t0)

a = chain([1] * n)
for _ in range(n):
    a = chain(a)
t0 = time()
print(sum(a), time() - t0)

print(sys.version)

Output (Try it online!):

10000 10000 0.0005640983581542969
10000 10000 0.0005021095275878906
10000 1.7817797660827637
3.7.4 (default, Jul  9 2019, 16:48:28) 
[GCC 8.3.1 20190223 (Red Hat 8.3.1-2)]

[serhiy-storchaka]

Is not this behavior the same since Python 2.4 (ad983e7)? cc @rhettinger