Document itertools.tee's internal batching

[jstriebel]

Add an impl-detail note to itertools.tee, explaining that CPython caches items in fixed-size batches of 57 items currently. This is relevant for iterators with memory-intensive items.

A small example showing the batching in action:

from itertools import tee

class LoudLifecycle:
    def __init__(self, i):
        self.i = i
        print(f"INIT {self.i}")

    def __del__(self):
        print(f"DEL {self.i}")

def my_iter():
    for i in range(100):
        yield LoudLifecycle(i)

a, b = tee(my_iter())

for _ in zip(a, b):
    pass

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33689974 | 📁 Comparing 9317c8f against main (bfd774d)

  🔍 Preview build  

1 file changed

± library/itertools.html

[picnixz]

We don't document such internals as they are subject to changes. It also came up in #138765. See also #138765 (comment).