There is a subsection in the description of news in version 3.13
which describes the modules removed from the standard library in this version.
Perhaps this isn’t even the first such removal of previous outdated modules and definitely not the last.
I suggest creating a separate page in the documentation, where a list of deleted modules with proposed replacements will be systematized according to python versions.
I think it can be done in the same way as it’s done in the table here
Just add it to the main documentation and update it afterwards. Then, so that, among other things, this page could get into the downloadable version of the documentation.
Of course there is such a page
But I think it’s better to make it even clearer.
Or if the table is further updated inside the PEP page then it can add all the PEPs to the downloadable version of the documentation.
I think it would be great to leave something behind about removed modules. If you search for the cgi module today, you find a 404 page. The original PEP had a table of replacements. That can be put in the docs, with redirects from the original module page to it.
That yes. But the current version of the documentation should only provide search by existing modules in the current version of python.
That’s why it’s so important to systematize the history of changes in the context of the current version.
It would also be useful to see the history of changes in tabular form for the entire api. But the existing version with footnotes is quite good too.
I don’t understand this: are you saying the latest Python docs shouldn’t find something useful if you search for “cgi”? I thought you wanted to provide information in the latest docs about the modules that have been removed?
Yes, the final information, i.e. the history of such modules, but all specific links to modules should lead to documentation of previous python versions.
As an example, the link https://docs.python.org/3.12/library/cgi.html leads to the documentation version in which this module was still available.
I have a different view. I think the ideal would be for the latest docs to have a cgi page that explains the module is gone, what version is was removed, a link to the latest version where it existed, and the recommended replacement.
People are surprised that things have been removed from the stdlib. We should do what we can to help them understand, and to help them adapt.
This will require changes in the current implementation. And a change in the very concept of documentation.
I doubt that all core developers will approve of this.
I like to argue with them myself but it usually doesn’t lead to anything good
That’s why I only asked for what is easy to add without changing the concept.
I’m not sure what you mean by changes in the implementation. If we wanted, we could have a cgi.rst file that talks about what happened to cgi. It would be published to cgi.html. If it needed to be in a different section, a redirect could take care of the move.
Maybe this isn’t broadly known: the documentation for modules in the stdlib is not made from docstrings in the .py files. Each module has its own .rst file for its docs.
About the concept of documentation: maybe I have an expansive idea of what documentation can be. I think it’s well within the purview of the Python docs to explain where deleted modules have gone.
First of all, we are talking about the concept of documentation. In the current concept, all links to something deleted lead to previous versions of the documentation. Previously, this mainly deleted APIs, now modules.
You also suggest storing all documentation for deleted items in the current version of the documentation. But python is not a backward compatible language. And here the core developers will clearly be against it.
Although there is no difference for me. If your option wins, I won’t mind
But I definitely want to have a cumulative systematized description of the history of deleted modules and their best replacements in the current version of the documentation.
Agreed. If searching for “cgi” just lead to an old page in 3.11 (or wherever it last existed) I wouldn’t notice the version. And I’d wonder why “import cgi” didn’t work.
I understand it can be frustrating to propose a change and have the core team refuse it. I’ve been in that position myself. But we shouldn’t over-anticipate opposition. Good ideas do get accepted. Change is possible.
But this isn’t what’s happening right now. docs.python.org/3/library/cgi.html currently doesn’t lead to docs.python.org/3.12/library/cgi.html, it leads to docs.python.org/3/. So you try to navigate to the documentation for the cgi module and get dumped on the home page. This is horrible UX.
Yes, it’s. But here again, the logic of the concept.
The link docs.python.org/3/library refers to the most recent version of python, not all third versions in the aggregate.
And this is again in the logic of a language without backward compatibility.
And the main problem is that the documentation doesn’t contain a summary table of these changes with links to previous documentation. The main documentation should have a transparent history of all changes.
And now there are too many references to PEPs. Then either need to include all PEPs in the main documentation or improve the main documentation.
