gh-103109: Add documentation for ignore_warnings

[CharlieZhao95]

• Add documentation for ignore_warnings
• Improve the comment in function ignore_warnings

• Issue: Improve the documentation for ignore_warnings #103109

[CAM-Gerlach]

Standard reminder: You can directly apply the suggestion below by simply clicking Commit suggestion, entering a descriptive commit message and then clicking Commit changes

One fix for some textual errors/issues, otherwise LGTM - thanks @CharlieZhao95 !

[CAM-Gerlach]

LGTM, thanks @CharlieZhao95 !

[erlend-aasland]

Please add a versionadded:: 3.8. Also, I think there's some relevant information in the docstring that should be included in the docs, namely that this decorator should be used with care since tools like git blame may become less useful with warnings suppressed. Forget that last part; too little coffee for me! ☕ ☕ ☕

Also note that there's a targeted variant called ignore_warnings_from (that's also undocumented¹).

Footnotes

1. Note that a lot of the test support functions are undocumented, some deliberately so, simply because they're mostly for internal use. ↩

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[erlend-aasland]

Oh BTW, would you mind reflowing this according to SemBr (within 79 chars line width)? If not, I'll do that before merging.

[CharlieZhao95]

would you mind reflowing this according to SemBr (within 79 chars line width)? If not, I'll do that before merging.

Oh! Thanks for your suggestion. I love these nits! This doesn't look too hard, I can try to get it done, and I'll try to follow the SemBr spec going forward. Improvements are always good! 😃

[CharlieZhao95]

Also note that there's a targeted variant called ignore_warnings_from (that's also undocumented1).

BTW, I didn't find the code that matches ignore_warnings_from, please let me know if it is my problem. :)

[CAM-Gerlach]

BTW, I didn't find the code that matches ignore_warnings_from, please let me know if it is my problem. :)

FWIW I couldn't find it either, grepping the codebase for that string and also searching the repo, issues, commits, PRs, etc. on GitHub (except for this one, of course).

[erlend-aasland]

Sorry, that was a typo on my side :) It's ignore_deprecations_from:

cpython/Lib/test/support/__init__.py

Lines 2217 to 2225 in c1e71ce

	def ignore_deprecations_from(module: str, *, like: str) -> object:
	token = object()
	warnings.filterwarnings(
	"ignore",
	category=DeprecationWarning,
	module=module,
	message=like + fr"(?#support{id(token)})",
	)
	return token

And, as far as I can see, it is only used in the tests for test.support, so there is no need to document it.

[CAM-Gerlach]

LGTM again, thanks @CharlieZhao95

[miss-islington]

Thanks @CharlieZhao95 for the PR, and @erlend-aasland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-103198 is a backport of this pull request to the 3.11 branch.

[bedevere-bot]

GH-103199 is a backport of this pull request to the 3.10 branch.