From eec64076e9b044116b1d52860a4c231e965ac7d8 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sun, 10 Aug 2025 03:55:42 +0530 Subject: [PATCH 1/4] Doc: Clarify flattening and bugfix for itertools.tee in 3.13 --- Doc/library/itertools.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index aa46920d3526f0..22a9de26c1f5cb 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -730,6 +730,29 @@ loops that truncate the stream. produced by the upstream :func:`tee` call. This "flattening step" allows nested :func:`tee` calls to share the same underlying data chain and to have a single update step rather than a chain of calls. + + .. note:: + + :func:`tee` automatically "flattens" existing tee objects, + sharing the same underlying buffer instead of nesting them, to avoid + performance degradation. This flattening behavior has existed since Python 3.7. + + .. versionchanged:: 3.13 + Fixed a bug where re-teeing the first iterator did not correctly flatten + the iterator chain in all cases. Previously, this could lead to unnecessary + nesting and performance degradation in rare scenarios. + + .. doctest:: + + >>> it = iter([1, 2, 3]) + >>> a, b = tee(it) + >>> c, d = tee(a) + >>> list(b) + [1, 2, 3] + >>> list(c) + [1, 2, 3] + >>> list(d) + [1, 2, 3] The flattening property makes tee iterators efficiently peekable: From 67fbdf2312e7427de0e7a1146ac6ac0cb5ab0353 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sun, 10 Aug 2025 04:22:06 +0530 Subject: [PATCH 2/4] Doc: Clarify flattening and bugfix for itertools.tee in 3.13 --- Doc/library/itertools.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 22a9de26c1f5cb..a8d02f66990672 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -730,7 +730,6 @@ loops that truncate the stream. produced by the upstream :func:`tee` call. This "flattening step" allows nested :func:`tee` calls to share the same underlying data chain and to have a single update step rather than a chain of calls. - .. note:: :func:`tee` automatically "flattens" existing tee objects, From d0317f71219dd742a26c5dbbaf6032e6488c76f5 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sun, 10 Aug 2025 04:57:53 +0530 Subject: [PATCH 3/4] Doc: Clarify flattening and bugfix for itertools.tee in 3.13 --- Doc/library/itertools.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index a8d02f66990672..049b0a8bcefead 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -730,16 +730,17 @@ loops that truncate the stream. produced by the upstream :func:`tee` call. This "flattening step" allows nested :func:`tee` calls to share the same underlying data chain and to have a single update step rather than a chain of calls. + .. note:: :func:`tee` automatically "flattens" existing tee objects, sharing the same underlying buffer instead of nesting them, to avoid - performance degradation. This flattening behavior has existed since Python 3.7. + performance degradation. .. versionchanged:: 3.13 - Fixed a bug where re-teeing the first iterator did not correctly flatten - the iterator chain in all cases. Previously, this could lead to unnecessary - nesting and performance degradation in rare scenarios. + Fixed a bug where re-teeing a tee iterator did not always return independent iterators. + Previously, the first iterator in the result could be the same object as the + input, causing inconsistent behavior. .. doctest:: From b608303fedb0524277ea6677a770b88b0467a07a Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sun, 10 Aug 2025 05:08:47 +0530 Subject: [PATCH 4/4] Doc: Clarify flattening and bugfix for itertools.tee in 3.13 --- Doc/library/itertools.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 049b0a8bcefead..133be4d4fd44c1 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -742,18 +742,6 @@ loops that truncate the stream. Previously, the first iterator in the result could be the same object as the input, causing inconsistent behavior. - .. doctest:: - - >>> it = iter([1, 2, 3]) - >>> a, b = tee(it) - >>> c, d = tee(a) - >>> list(b) - [1, 2, 3] - >>> list(c) - [1, 2, 3] - >>> list(d) - [1, 2, 3] - The flattening property makes tee iterators efficiently peekable: .. testcode::