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

[Aniketsy]

(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/

[pochmann3]

Why do you say since 3.7? It existed in Python 2 already.

[Aniketsy]

Apologies for the oversight. Would it be fine if I remove this sentence and just describe the behavior without referencing a specific version history?

[pochmann3]

I don't think so. It's described in the current documentation already.

[pochmann3]

I don't see how that bug led to unnecessary nesting and performance degradation. I think you misunderstood it.

[Aniketsy]

.. 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!

[pochmann3]

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.

[Aniketsy]

Thanks for pointing that out! I’ll pause work on this and wait for clarification .

[pochmann3]

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.

[rhettinger]

A few thoughts:

• We don't normally put versionchanged or versionadded markup for bugfixes. That is for new features.

• Trey's note presumed that flattening was new. That feature has always been present. There was a bug in the feature that went unnoticed. That has been fixed everywhere that we're allowed to fix it.

• The bugfix was backported to 3.12 and is in all versions of Python that aren't in security-fix-only status. Python 3.14 is about to be final, so it will be in a new supported version as well.

• The existing text already calls out self-flattening behavior, so ISTM the new text would be redundant. Also the pure python equivalent has explicit logic for tee flattening.

Thanks. for the PR but it should be declined because it is based on a faulty premise.