gh-92611: Link to section for PEP 594 modules; mention rm version & alternatives

[CAM-Gerlach]

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 Enforce the use of deprecated-removed in docs #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

• 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 Enforce the use of deprecated-removed in docs #92564)

.. deprecated:: 3.11 was intentional. From #31891 (comment):

[...] the SC wanted to leave out target removal versions in the docs in case we have to change something due to feedback (in the code itself via the warnings.warn call still makes sense).

Edit: let's discuss in #92564, see #92564 (comment).

Edit: let's discuss in #92564, see #92564 (comment).

(Already replied to you over there)

@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.

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.
🐍🍒⛏🤖

GH-92785 is a backport of this pull request to the 3.11 branch.

GH-92786 is a backport of this pull request to the 3.10 branch.

GH-92787 is a backport of this pull request to the 3.9 branch.

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.