Following on from the discussion in History of “dead batteries”, I’ve made a pull request showing my proposed approach: Docs: re-create cgi and cgitb pages to document their removal.
This shows two modules, cgi and cgitb. If the approach is approved, I’ll flesh it out with the rest of PEP 594.
Comments welcome on the pull request.
Would we consider a general ‘this module has been removed’ page?
The redirects file has entries relating to modules removed in Python 2, and I can quite easily see us having a preponderance of stub documents like these in 10 years’ time. A single ‘removed’ page is probably easier to maintain and point people to, although it might have less tailored guidance. [1]
A
I might also argue that we shouldn’t provide such guidance, as by providing it we become responsible for it, and the point of removing modules is to reduce maintenance. ↩︎
On the question of providing guidance: Mostly I’ve just copied what was in the What’s New entry for the removal. The link to legacy-cgi is new, and the most helpful part.
About stub pages: we might have to have a bunch of stub pages, but most will be simple mentions of the removal. More pages means fewer redirects, so there’s a trade-off between those.
I think this is a great idea and helpful for users. The current system (where https://docs.python.org/3.14/library/cgi.html redirects to the top-level docs page) doesn’t tell users anything about what happened to the module.
Adding these pages will have some maintenance cost, but they’re unlikely to need a lot of changes in the future, and I think it’s worth the cost.
The thing I like about the multiple pages is that I can select previous versions to find the old docs, if needed. A single removal page would lose that, although it would be easier to update all such docs at once.
As to whether tailored guidance implies support, maybe it would be good to have an admonition on these pages that explains that third-party modules are a convenience maintained by community members and are unsupported by CPython.
The thing I like about the multiple pages is that I can select previous versions to find the old docs, if needed.
Oh, I meant to include a link to the last version where the module was supported. I forgot to do that, but I’ll add it.
LGTM! The one thing I was looking for was these modules to be listed in the top level Deprecations page. Did I miss that?
I don’t know why they aren’t there. They weren’t added to that page when the modules were removed in the first place.
@nedbat Sorry, just meant to say that I like that this version menu works if we keep the doc location the same:
Nothing wrong with an additional link to the last release, though.
I’ve added the rest of the PEP 594 modules to the pull request:
List of removed stdlib modules per Python version:
asynchat, asyncore, distutils, imp, smtpd.binhex.formatter, parser, symbol.dummy_threading, _dummy_thread.macpath.fpectl, macurl2path.Details: Python standard library.
I don’t think that we should keep the doc for all of these removed modules, except for distutils and imp maybe.
If the module docs need to be removed eventually, I would suggest targeting the EOL of the first version where the module was removed. If I somehow stalled on 3.11 until its EOL, then I will have one year when all stable versions (3.12-3.16) tell me what happened.
I’ve merged my pull request to restore doc pages, but it doesn’t include all of these. I got started down this path because of actual people asking where the docs went for some deleted modules, in particular cgi and audioop.
We can continue to iterate if needed.
Sorry if this is a cache issue, but when I try to follow the links on the removed modules page, all links besides distutils and imp lead to the home page.
As mentioned in the pull request, the redirects added here need to be changed too, which is not done yet it seems.