Repository navigation
Doc: Deprecation notices in modules to be removed per PEP 594 could be clearer and more helpful #92611
Description
Activity
- changed the title
[-]Doc: Links to PEP 594 in modules it deprecates don't go directly to the relevant section[/-][+]Doc: Deprecation notices in modules to be removed per PEP 594 missing critical links and details[/+]on May 10, 2022 PR opened as #92612
This resulted in even a highly experienced Python developer like @fungi being unable to discover that information, who ended up having to dig through old threads to find it.
To be fair to the PEP authors and reviewers, a lot of this was down to my personal biases. I've been conditioned through the years not to expect this degree of specificity for recommendations within PEPs and so didn't even look for it there. Worse, I read through the PEP many times before it was approved, and yet still completely failed to remember it was in there when I wound up needing to do something about it.
Many thanks to everyone who put hard work into making PEP 594 so thorough.
Reacted by C.A.M. Gerlach- changed the title
[-]Doc: Deprecation notices in modules to be removed per PEP 594 missing critical links and details[/-][+]Doc: Deprecation notices in modules to be removed per PEP 594 could be clearer and more helpful[/+]on May 10, 2022 Thanks for the insight, @fungi ! Just to be clear, I didn't mean to imply that this was the fault of anyone, including the PEP authors/reviewers (of which I was one of the latter) or those who added these messages in the docs, and I apologize if I sent that impression. I've seen first-hand how its easy to miss things like this when I'm the person writing the docs and intimately familiar with the subject area, even if its something that really sticks out to a typical reader.
Do note that any use of
deprecated-removedcan't be backported as the SC explicitly asked removal targets to not be backported to older versions of the docs.See my response on issue #92564 regarding the broader issue, and my message on PR #92612 for a path forward to drop that change for now on that PR.
5 remaining items
- added 3 commits that reference this issue
on May 13, 2022 - added a commit that references this issue
on May 20, 2022 - added a commit that references this issue
on Jun 11, 2022 - added a commit that references this issue
on Jun 26, 2022
As most recently discussed in the Discourse thread on @brettcannon and @tiran 's PEP 594 (PEP-594), there have been a number of questions various places about the replacement for
cgi.parse_headers()(and several other othercgiutility functions) deprecated by that PEP.The PEP actually contains a good chunk of useful information that addresses this, but it is (evidently) not that easy to find deep in the body text, particularly for the important case of users coming from the
cgimodule docs, which only features a brief note to see the PEP for details, without a direct link to said section, information on replacements or even the target removal version (which provides no clear indication of the urgency to the removal, particularly for modules (likeimp) that have been formally or "soft" deprecated for many years or even decades).Therefore, users have to scroll through the PEP to find any such information, and the first thing they will come across mentioning
cgiis the table, which indicates there is no replacement (nor does it link to thecgisection several pages further down containing that information). This resulted in even a highly experienced Python developer like @fungi being unable to discover that information, who ended up having to dig through old threads to find it.This turns out to be the case for nearly all such modules. Therefore, to improve the user experience here and raise the visibility of the pending removal, we should:
deprecated-removedto clearly indicate to users that a removal version is planned and what it is, so they can prepare accordingly or voice any unanticipated impacts (as discussed in Enforce the use ofdeprecated-removedin docs #92564)I will open a PR momentarily to take care of these three items.
Also, related issues:
uuencode/decode-related functions in thebinasciimodule, as well as theuucodec will also be deprecated, but as far as I can tell, those deprecations are neither yet implemented nor documented (will open a separate issue)