As discussed in #92611 , currently the experience is pretty subpar for users trying to get even basic information about the deprecations from PEP 594 in the relevant modules' docs. To improve this and increase the visibility of the pending removal, this PR

• Links 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-links 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)
• Uses 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 #92564) Deferred to a 3.11+ PR for now.
• Add additional replacement information for functions in the cgi module, per requests Deferred to a 3.11+ PR

Also, despite having been deprecated for many versions without any mention of imminent removal, the imp module is due to be removed in Python 3.12, but no indication of that is given in the documentation, which this also resolves.

Fixes #92611

Member

hugovk commented May 10, 2022 •

@brettcannon Per your helpful advice on the Discourse thread, I've added individual deprecation notices to the cgi utility functions discussed in the PEP, with information on replacements for each, and a similar note up top for FieldStorage.

I can bring the broader issue up with the Docs WG Editorial Board, but in order to allow backporting of the initial fix described in the issue and on the thread, with the link not pointing to the correct section of the PEP for each deprecation and resulting in increased user confusion and traffic asking about a replacement (or expressing concern about the apparent lack thereof), I can drop commit 76f04e1 adding deprecated-removed (specifically structured as such in case that became necessary) and that can be applied just to 3.11+ as an immediate followup PR.

However, one question remains—should the additional explanations mentioned above and added in c937d01 also be backported (if so, I would modify them to remove the removal version for this PR), or left 3.11+ only as well? Let me know, and I'll either move both commits to another branch for a followup 3.11+ only PR, or just drop/move 76f04e1 and edit c937d01 to not use deprecated-removed.

However, one question remains—should the additional explanations mentioned above and added in c937d01 also be backported (if so, I would modify them to remove the removal version for this PR), or left 3.11+ only as well? Let me know, and I'll either move both commits to another branch for a followup 3.11+ only PR, or just drop/move 76f04e1 and edit c937d01 to not use deprecated-removed.

@brettcannon While I didn't see any response, I'm assuming you're okay with the additional explanations being 3.11-only in light of your approval here and your call on #92613 regarding those deprecations. Therefore, I've gone with the simpler first option for now and just moved everything to another 3.11-only branch but everything except for the commit fixing PEP links to point directly to the relevant sections and linking any stdlib replacements (which, of course, does have to be backported to fix the existing message, as otherwise, those reading the existing message in the 3.9 and (default) 3.10 docs will continue to be confused).

I've gone with the simpler first option for now and just moved everything to another 3.11-only branch but everything except for the commit fixing PEP links to point directly to the relevant sections and linking any stdlib replacements (which, of course, does have to be backported to fix the existing message, as otherwise, those reading the existing message in the 3.9 and (default) 3.10 docs will continue to be confused).

Sorry, but that's a lot of words with nested parentheses and I'm sick, so my brain can't fully process what you're saying. I think you're just saying you yanked the deprecated-removed part from this PR, which is fine.

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

…ecation notices (pythonGH-92612)

(cherry picked from commit 9f68dab)

Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>

Thanks for your help and merging, @brettcannon

Sorry, but that's a lot of words with nested parentheses and I'm sick, so my brain can't fully process what you're saying.

Sorry, its my fault—I realized my original explanation was rather dense, buried and overcomplicated so I rewrote it in that comment, but I kept adding to it and it ended up being as complex as the original 😞

Take care of yourself, and I hope you feel better!

I think you're just saying you yanked the deprecated-removed part from this PR, which is fine.

Yep, basically, except that I also yanked the per-function cgi deprecation messages (which is the part my question was asking about as to whether you wanted that backported...which I should have just asked in one simple sentence).

I'll make two separate PRs, one with each, and if you'd like the per-function deprecation messages backported, I can drop the deprecated-removed from there and add it for 3.11+ in the non-backported deprecated-removed PR.