Repository navigation
Doc: Deprecation notices in modules to be removed per PEP 594 could be clearer and more helpful #92611
Description
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 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-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:
- 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 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)
Activity
[-]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[/+]CAM-Gerlach commentedon May 10, 2022
PR opened as #92612
fungi commentedon May 10, 2022
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.
[-]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[/+]CAM-Gerlach commentedon 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 commentedon May 11, 2022
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.CAM-Gerlach commentedon May 12, 2022
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
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…
gh-92611: Link to PEP 594 sections & add key detail in doc deprecatio…
gh-92611: Clarify planned removal version in PEP 594-deprecated modul…
pythongh-92611: Clarify planned removal version in PEP 594-deprecated…
gh-92611: Clarify planned removal version in PEP 594-deprecated modul…
pythongh-92611: Link to PEP 594 sections & add key detail in doc depr…
pythongh-92611: Add details on replacements for cgi utility funcs
gh-92611: Add details on replacements for cgi utility funcs (GH-92792)
pythongh-92611: Add details on replacements for cgi utility funcs (py…
gh-92611: Add details on replacements for cgi utility funcs (GH-92792) (
Revert 30935 defer bpo45162 to 312 (#94285)
pythongh-92611: Clarify planned removal version in PEP 594-deprecated…