GeezerVison is showing github.com — Doc: Deprecation notices in modules to be removed per PEP 594 could be clearer and more helpful · Issue #92611 · python/cpython
Doc: Deprecation notices in modules to be removed per PEP 594 could be clearer and more helpful #92611DescriptionAs 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 other cgi utility 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 cgi module 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 (like imp) 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 cgi is the table, which indicates there is no replacement (nor does it link to the cgi section 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:
- Link directly to each module's section in the PEP (so users can easily access the relevant information)
- For those with direct replacements with other stdlib modules, directly internal-link such as well (so users don't have to click through to the PEPs and then back to the docs first, which also won't preserve the version and translation they are on)
- Use the proper
deprecated-removed to 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 of deprecated-removed in docs #92564)
I will open a PR momentarily to take care of these three items.
Also, related issues:
- We should link the table entries to their sections to allow users linked to the PEP to navigate it much more easily (will open a PR on the PEPs repo)
- The PEP states that the
uuencode/decode-related functions in the binascii module, as well as the uu codec will also be deprecated, but as far as I can tell, those deprecations are neither yet implemented nor documented (will open a separate issue)
Activitychanged 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, 2022CAM-Gerlach commented on May 10, 2022 fungi commented on May 10, 2022
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, 2022CAM-Gerlach commented 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. brettcannon commented on May 11, 2022 Do note that any use of deprecated-removed can't be backported as the SC explicitly asked removal targets to not be backported to older versions of the docs. CAM-Gerlach commented on May 12, 2022 added 3 commits that reference this issue on May 13, 2022gh-92611: Link to PEP 594 sections & add key detail in doc deprecatio… gh-92611: Link to PEP 594 sections & add key detail in doc deprecatio… gh-92611: Link to PEP 594 sections & add key detail in doc deprecatio… added 2 commits that reference this issue on May 20, 2022gh-92611: Clarify planned removal version in PEP 594-deprecated modul… pythongh-92611: Clarify planned removal version in PEP 594-deprecated… added a commit that references this issue on May 20, 2022gh-92611: Clarify planned removal version in PEP 594-deprecated modul…
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|