gracefully update the behavior of the buffering argument to open to support buffered text streams too

[cosmicexplorer]

Problem

Mansoor Ahmed wrote one of the best bug reports I've ever seen in my entire life at https://bugs.python.org/issue30718, regarding how the buffering argument to the standard builtin open() i/o method is unusable for text buffers as a result of double-buffering. @slateny then followed up to modify the documentation in #32351.

This began because I didn't understand the current language used to refer to double buffering, and after having dived into it a bit I have come to agree with Mansoor that there is no useful way to apply the double buffering that results when specifying a positive number greater than 1 for a text stream.

Solution

Since this issue was first raised, there have been a few changes to the C-level API of TextIOWrapper objects. In particular, they now support specifying the write_through option directly in the constructor. I believe this fixes a very uncharacteristic "sharp edge" that users can run into working with python.

I spent some more time advancing the documentation and included the code sample @izbyshev provided way back in 2017, as I thought it made the operations happening in C code make much more sense.

I believe however that the list layout I chose which uses asterisks is not quite right and may break the docs. I'm not fully sure because I found the docs extremely difficult to generate and am working on fixing that separately.

Thank you for your time. I hope to work further with CPython in the future.

---

📚 Documentation preview 📚: https://cpython-previews--139566.org.readthedocs.build/

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[cosmicexplorer]

This will definitely require a NEWS entry as it changes user-visible behavior in an extremely commonly used interface. The only reason I thought that would be remotely acceptable is that I could not figure out how the current behavior for buffering > 1 for text streams could ever be used intentionally.

[picnixz]

This would require more than a NEWS entry. It may require a PEP as well, but we would definitely need an issue. Now, instead, I would first expect that a https://discuss.python.org/c/ideas/6 thread is created first before opening an issue. We need to know whether there would be real usecases.

If the proposal is accepted, you'll eventually need to update the Python implementation and definitely add tests. So, sorry but this feature request is way too important for skipping this process, hence I'm going to close the PR for now.

[cosmicexplorer]

Ok, I have been in the midst of proposing several python packaging PEPs recently so that's not too hard. I am very good at writing tests but was thinking it would be easier to propose earlier to get exactly this kind of feedback on how to proceed. Thanks so much for your time.