Add note about filtering warning #7839
Conversation
Dreamsorcerer
added
bot:chronographer:skip
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #7839 +/- ##
=======================================
Coverage 97.40% 97.40%
=======================================
Files 106 106
Lines 32142 32142
Branches 3738 3738
=======================================
Hits 31307 31307
Misses 631 631
Partials 204 204
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
|
|
||
| If warnings are explicitly enabled (e.g. ``-We`` or ``-Wall``) then | ||
| using :class:`str` keys will trigger a warning. Like other warnings | ||
| this can be filtered out easily if you have no interest in this feature. |
There was a problem hiding this comment.
pet peeve! 'easy' should never be used in documentation; things are easy when you know how to do them, if you are reading documentation then this is prior to you knowing how to do them :)
There was a problem hiding this comment.
That's a good point! I occasionally hear tech writers mentioning this, but it's so often overlooked. We need to do better!
There was a problem hiding this comment.
I don't really mind either way, but I personally don't get it. It's easy in the context of the documentation, as you only need to copy a line of code or CLI argument. Plenty of things are still difficult after you know how to do them. The word doesn't add anything of value to the docs though, so it makes sense to remove it for that reason, if we do merge it in.
There was a problem hiding this comment.
@Dreamsorcerer it appears we failed to convey the complete context of the sentiment.
The point here is not that it's objectively easy or hard in the context, but how it affects the receiving side of the text (the reader).
When people hear (see) certain words, they have an effect on their perception. It's a subconscious thing. Hearing “just” often makes people feel dumb. They get defensive and don't accept the information as easily. This is not the recommendation for docs only, it's applied to all the teaching contexts (tutoring/mentoring/training/coaching/public speaking etc.)
The solution that is typically suggested is avoiding the use of such trigger words (or phrases). The same goes for saying “easy” / “straightforward” / “obvious” / “intuitive”. All of these have a great potential to discourage and hurt self-confidence of the readers. The less experience one has, the more harmful it is. This is a straight way to diminish people's feeling of achievement.
Instead, of using these, it's recommended to just skip to the explanation, without showing how much the writer is smarter than a reader.
There was a problem hiding this comment.
@webknjaz I made a toot; i think we can stop annoying Dreamsorcerer any more :)
https://mastodon.green/@eoghanmurray/111521647225842098
| If warnings are explicitly enabled (e.g. ``-We`` or ``-Wall``) then | ||
| using :class:`str` keys will trigger a warning. Like other warnings | ||
| this can be filtered out easily if you have no interest in this feature. | ||
| e.g. Add ``-W 'ignore:It is recommended to use web.AppKey instances for keys.'`` |
There was a problem hiding this comment.
I usually prefer to be as narrow as possible when making such exclusions:
| e.g. Add ``-W 'ignore:It is recommended to use web.AppKey instances for keys.'`` | |
| e.g. Add ``-W 'ignore:It is recommended to use web.AppKey instances for keys.:aiohttp.web_exceptions.NotAppKeyWarning:aiohttp.web_app'`` |
(although I'm not sure that the module part of the spec is right, because of the stacklevel, maybe drop it from my suggestion)
Can we advertise this? Besides, it's an “advanced” document.
There was a problem hiding this comment.
I'm afraid it's not valid either way, otherwise I would have just used the type alone which is perfectly accurate: python/cpython#66733
I'm tempted to not merge this in, as nobody else has reported any concerns. The original report was from someone using 3.9.0b0, which wasn't filtering out the warnings by default. Nobody who explicitly enabled warnings has expressed any concerns with the presence of these warnings.
There was a problem hiding this comment.
It's not? For some, I was convinced that I saw this work in cases when importing the exception wasn't causing it...
There was a problem hiding this comment.
It basically only works when you manipulate the PYTHONPATH beforehand: python/cpython#66733 (comment)
Otherwise, the warnings filters are resolved before the import paths are resolved. Requiring PYTHONPATH manipulation is not a robust enough experience to recommend in the docs.
There was a problem hiding this comment.
I'll close this for now, as I've not seen any other user reports. Will reopen it if anybody reports any concerns over the warning.
No description provided.