gh-129846: clarify suppression of warning output in catch_warnings

[Mr-Sunglasses]

Issue: #129846

• Issue: warnings.catch_warnings docs: dubious mention of sys.stdout #129846

[StanFromIreland]

I think we should drop the note and just integrate it above.

[Mr-Sunglasses]

tagging @sobolevn for a review. TiA.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[serhiy-storchaka]

While we are here, I suggest few more changes.

• Replace :const:`False` and :const:`True` with simple false and true. Any value is accepted, not only these singletons.
• Replace :class:`None` with ``None``. It is not a class.
• Start the new sentence from the new line. We change this line in any case, this will minimize changed lines in future.
• Mention that :func:`showwarning` is reset to the default implementation.
• Maybe the sentence can be changed more, it looks complicated like "The House That Jack Built".

[serhiy-storchaka]

@StanFromIreland, could you please review the current variant?

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32918634 | 📁 Comparing 875e10d against main (2c20f9c)

  🔍 Preview build  

3 files changed

± library/binascii.html
± library/warnings.html
± whatsnew/changelog.html

[picnixz]

Note: we don't use conventional commits headings

[StanFromIreland]

Hmm, should this be fixed too:

cpython/Lib/_py_warnings.py

Lines 712 to 720 in 56bd9ea

	if self._record:
	if _use_context:
	context.log = log = []
	else:
	log = []
	self._module._showwarnmsg_impl = log.append
	# Reset showwarning() to the default implementation to make sure
	# that _showwarnmsg() calls _showwarnmsg_impl()
	self._module.showwarning = self._module._showwarning_orig

[serhiy-storchaka]

The code does not match the documentation. This can be a separate bug.

[serhiy-storchaka]

This was changed in #146358, but now not only the code does not match docs, but I am not sure that context_aware_warnings have not lost its meaning.