gh-110893: Improve docs for __future__ module

[anujrmohite]

Related Issue

#110893 Improvements in the documentation future module

Changed file:

Doc/library/future.rst

---

📚 Documentation preview 📚: https://cpython-previews--112348.org.readthedocs.build/en/112348/library/__future__.html

• Issue: Improve the documentation for __future__ #110893

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[anujrmohite]

hey @merwok @nedbat ,
I've submitted a PR... . Could you please take a look? Your feedback and review are highly appreciated.
Thanks!

[anujrmohite]

hey @merwok @hugovk, I've finished the changes. Please review at your convenience.
Happy to make any further adjustments if needed.

[hauntsaninja]

Thank you for the PR and for contributing to CPython!

However, I think this still isn't clear enough about the ways in which __future__ is special, and the ways in which it is normal. I think this also regresses clarity in a few ways, e.g. talking about OptionalRelease and MandatoryRelease before these terms are defined, losing the fact that MandatoryRelease is only a prediction and not a guarantee, etc. I merged https://github.com/python/cpython/pull/114642/files which attempts to address the first point here.

[terryjreedy]

A separate PR has made an alternate replacement of the initial 3 bullet points. Both replacements need to be read and merged into one expanded replacement.

[nineteendo]

Could someone solve the merge conflicts?

[terryjreedy]

@JelleZijlstra Could you fix the merge conflicts between your PR and the first 3 paragraphs of this PR? I don't care or have any opinion how. If you think your version completely supercedes what it conflicts with, and no merging is needed, it would be trivial.

[JelleZijlstra]

I fixed the merge conflict between @hauntsaninja's PR that I merged some time ago and this one. I picked the text that we already have for the introductory paragraphs.

The remaining changes in this PR don't solve any real problem as far as I can see, and I generally prefer the current wording over the changes in this PR. So I suggest closing this PR.

With the merge resolution I pushed, this PR no longer removes the bullet points at the top of the __future__ documentation that justify the design. Possibly those should be removed or moved, as they're not that relevant to current usage.

[merwok]

I agree with Jelle!