gh-137597: Clarify flattening and bugfix for itertools.tee #137599
Conversation
Doc/library/itertools.rst
Outdated
|
|
||
| :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. |
There was a problem hiding this comment.
Why do you say since 3.7? It existed in Python 2 already.
There was a problem hiding this comment.
Apologies for the oversight. Would it be fine if I remove this sentence and just describe the behavior without referencing a specific version history?
There was a problem hiding this comment.
I don't think so. It's described in the current documentation already.
Doc/library/itertools.rst
Outdated
|
|
||
| .. 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 |
There was a problem hiding this comment.
I don't see how that bug led to unnecessary nesting and performance degradation. I think you misunderstood it.
There was a problem hiding this comment.
.. versionchanged:: 3.13
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.
Is this description accurate, or have I misunderstood the nature of the bug?
Please let me know if I’m mistaken.
Thank you!
There was a problem hiding this comment.
That description is accurate and you seem to have misunderstood it. Before jumping to a PR, I suggest to first wait for Trey to clarify what he means, and possibly for Raymond to comment on it. I suspect Trey is talking about that bug(fix) and Raymond didn't forget to add a note but intentionally didn't add one.
There was a problem hiding this comment.
Thanks for pointing that out! I’ll pause work on this and wait for clarification .
Doc/library/itertools.rst
Outdated
| >>> list(c) | ||
| [1, 2, 3] | ||
| >>> list(d) | ||
| [1, 2, 3] |
There was a problem hiding this comment.
What is the purpose of this? It has nothing to do with the bug and its fix, and seems to just redundantly show what the existing peeking example shows already.
(GH#137597)
This PR updates the documentation for itertools.tee to clarify its flattening behavior when called on existing tee objects. It adds a "Changed in version 3.13" note describing the bugfix for re-teeing the first iterator, and includes a doctest example to illustrate that repeated tee calls do not cause deep nesting.
Please let me know if this fix needs any improvements . I’m open to feedback and happy to make changes based on suggestions.
Thankyou!
📚 Documentation preview 📚: https://cpython-previews--137599.org.readthedocs.build/