gh-56229: Document flush expectation for stdout and stderr replacements

[ahmojo]

Summary

Document that replacement sys.stdout and sys.stderr objects should provide flush() because these streams are flushed during interpreter shutdown.

What changed

• Added one focused sentence to Doc/library/sys.rst.
• No behavior changes.
• No new dependencies.

Tests

• git diff --check
• Doc\make.bat check
• Full Sphinx HTML build with --fail-on-warning

Closes #56229

• Issue: [doc] Attribute error with flush on stdout,stderr #56229

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33451108 | 📁 Comparing 3c4b232 against main (93b1a88)

  🔍 Preview build  

1 file changed

± library/sys.html

[cmaloney]

I don't think this is correct to do or entirely accurate. The reason why .flush() is required is not because the CPython shutdown code requires it. Instead, it's because file-like objects which are garbage collected call .close() and that, in the CPython I/O stack calls .flush(). The interpreter shutting down doesn't require that file-like objects auto close on deletion nor that closing implies flushing.

My leaning is no new documentation here. Reading through the issue I think we should close it. The core issue was that code was always erroring but those errors used to be suppressed but are now shown thanks to improvements in error reporting. This falls into the general class of "make sure finalization works right" for custom I/O object stacks. In current CPython replacement with StringIO works well.

For custom objects what is required depends on how they are implemented.

also: Please do not force-push to CPython PR branches: https://devguide.python.org/getting-started/pull-request-lifecycle/#don-t-force-push

[cmaloney]

Thanks for the PR @ahmojo ! The text you came up with is good but unfortunately the original issue should have been closed earlier per reasoning in my last post. Thank you for the work and looking forward to your next CPython contribution :)