Doc: Deprecation notices in modules to be removed per PEP 594 could be clearer and more helpful · Issue #92611 · python/cpython (original) (raw)

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-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)