gh-152397: Provide a cross-reference to PEP 798 unpacking syntax

[rhettinger]

• Issue: the itertools.chain.from_iterable docs should gain a short note pointing readers PEP 798 alternative #152397

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33339473 | 📁 Comparing 0061979 against main (003d362)

  🔍 Preview build  

1 file changed

± library/itertools.html

[miss-islington-app]

Thanks @rhettinger for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @rhettinger for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @rhettinger for the PR 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-152458 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-152459 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-152460 is a backport of this pull request to the 3.15 branch.

[rhettinger]

hugovk Thanks for doing the 3.15 backport.

I'm not sure it makes sense for 3.14 and 3.13 though. PEP 798 is a 3.15 feature.

[nedbat]

Can we change the PEP reference to a link to the syntax description in the docs? And add a "since 3.15" mention?

[nedbat]

I made a pull request with the change: #152462

[rhettinger]

My preference is to keep the PEP reference because it best describes the relationship between the new unpacking syntax and the existing itertool functions. Also, the syntax docs in the language reference are rather technical and sometimes difficult to follow. However, if you feel strongly about replacing the PEP reference, I would be happy to make the edit.

I don't feel like the chain docs are the right place for a 3.15 versionadded note. That belongs with the syntax docs and in the PEP. I can't think of other places where versionadded is used in a simple here-are-two-ways-to-do-it code examples. As a reader of the chain docs, I would find a version note to be confusing because chain itself has been stable for decades.

[bedevere-app]

GH-152460 is a backport of this pull request to the 3.15 branch.

[nedbat]

True, in my pull request I left out the version mention, since the language reference has it. The language reference also has a link to the PEP if people are interested.

The PEP itself starts with:

Important

This PEP is a historical document. The up-to-date, canonical documentation can now be found at Displays for lists, sets and dictionaries, Dictionary displays.

I don't think we should send people outside the docs only for them to find a sign that says they should go back to the docs.