From 9317c8f98d646012282814a779d065158b03b737 Mon Sep 17 00:00:00 2001 From: Jonathan Striebel Date: Tue, 21 Jul 2026 16:26:22 +0200 Subject: [PATCH] Document itertools.tee's internal batching 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. --- Doc/library/itertools.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index e1730608887b3dd..4e65a4747cc129c 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -757,6 +757,14 @@ loops that truncate the stream. most or all of the data before another iterator starts, it is faster to use :func:`list` instead of :func:`tee`. + .. impl-detail:: + + Internally, CPython's :func:`tee` groups cached items into fixed-size + batches (57 items each currently) and only frees a batch once all + iterators have consumed it. Memory usage is thus bounded by the gap + between the fastest and slowest iterator plus up to one batch, not by + that gap alone. + .. function:: zip_longest(*iterables, fillvalue=None)