Doc: Deprecation notices in modules to be removed per PEP 594 could be clearer and more helpful #92611
Comments
CAM-Gerlach
changed the title
|
PR opened as #92612 |
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. |
CAM-Gerlach
changed the title
|
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. |
|
Do note that any use of |
|
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. |
…ecation notices (pythonGH-92612) (cherry picked from commit 9f68dab) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
…ecation notices (pythonGH-92612) (cherry picked from commit 9f68dab) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
…ecation notices (pythonGH-92612) (cherry picked from commit 9f68dab) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
…es (GH-92793) As discussed in #92611 and #92564 and as a followup to PR #92612 , this 3.11+ only PR uses the proper `deprecated-removed` role for the modules deprecated by PEP 593 (PEP-594) 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. Related to #92792 ; if we decide to backport that PR, the upgrade to using `deprecated-removed` on those functions can be moved to this one.
… modules (pythonGH-92793) As discussed in pythonGH-92611 and pythonGH-92564 and as a followup to PR pythonGH-92612 , this 3.11+ only PR uses the proper `deprecated-removed` role for the modules deprecated by PEP 593 (PEP-594) 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. Related to pythonGH-92792 ; if we decide to backport that PR, the upgrade to using `deprecated-removed` on those functions can be moved to this one. (cherry picked from commit 31fa41e) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
…es (GH-92793) (GH-93026) As discussed in GH-92611 and GH-92564 and as a followup to PR GH-92612 , this 3.11+ only PR uses the proper `deprecated-removed` role for the modules deprecated by PEP 593 (PEP-594) 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. Related to GH-92792 ; if we decide to backport that PR, the upgrade to using `deprecated-removed` on those functions can be moved to this one. (cherry picked from commit 31fa41e) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
…ecation notices (pythonGH-92612) (cherry picked from commit 9f68dab) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
Per @brettcannon 's [suggestions on the Discourse thread](https://discuss.python.org/t/pep-594-take-2-removing-dead-batteries-from-the-standard-library/13508/51), discussed in #92611 and as a followup to PR #92612 , this PR add additional specific per-function replacement information for the utility functions in the `cgi` module deprecated by PEP 594 (PEP-594). @brettcannon , should this be backported (without the `deprecated-removed` , which I would update it accordingly and re-add in my other PR adding that to the others for 3.11+), or just go in 3.11+?
…thonGH-92792) Per @brettcannon 's [suggestions on the Discourse thread](https://discuss.python.org/t/pep-594-take-2-removing-dead-batteries-from-the-standard-library/13508/51), discussed in pythonGH-92611 and as a followup to PR pythonGH-92612 , this PR add additional specific per-function replacement information for the utility functions in the `cgi` module deprecated by PEP 594 (PEP-594). @brettcannon , should this be backported (without the `deprecated-removed` , which I would update it accordingly and re-add in my other PR adding that to the others for 3.11+), or just go in 3.11+? (cherry picked from commit 71354adff07f8beba8374767532bb9da34546e66) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
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 othercgiutility 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
cgimodule 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 (likeimp) 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
cgiis the table, which indicates there is no replacement (nor does it link to thecgisection 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:
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 #92564)I will open a PR momentarily to take care of these three items.
Also, related issues:
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)The text was updated successfully, but these errors were encountered: