This PEP proposes a strategy for migrating the default version of thePython documentation presented to users of Python when accessingdocs.python.org from 2.7 to Python 3.3.
It proposes a backwards compatible scheme that preserves the meaning ofexisting deep links in to the Python 2 documentation, while stillpresenting the Python 3 documentation by default, and presenting thePython 2 and 3 documentation in a way that avoids making the Python 3documentation look like a second-class citizen.
With the transition of the overall Python ecosystem from Python 2 to Python 3still in progress, one question which arises periodically[1],[2] is whenand how to handle the change from providing the Python 2 documentation asthe default version displayed at the docs.python.org root URL to providingthe Python 3 documentation.
There are a couple of key concerns that any migration proposal needs toaddress.
Many beginners learn Python through third party resources. These resources,not all of which are online resources, may reference in to the python.orgonline documentation for additional background and details.
Importantly, even when the online documentation is updated, the “versionadded” and “version changed” tags usually provide enough information forusers to adjust appropriately for the specific version they are using.
While deep links in to the python.org documentation may occasionally breakwithin the Python 2 series, this is very rare.
Migrating to Python 3 is a very different matter. Many links would break dueto renames and removals, and the “version added” and “version changed”information for the Python 2 series is completely absent.
There are many useful Python resources out there, such as the mailing listarchives on python.org and question-and-answer sites like Stack Overflow,where links are highly unlikely to be updated, no matter how much noticeis provided.
Old posts and answers to questions all currently link to docs.python.orgexpecting to get the Python 2 documentation at unqualified URLs. Links fromanswers that relate to Python 3 are explicitly qualified with/py3k/ inthe path component.
This PEP (based on an idea originally put forward back in May[3]) is tonot migrate the Python 2 specific deep links at all, and instead adopt ascheme where all URLs presented to users on docs.python.org are qualifiedappropriately with the relevant release series.
Visitors to the root URL athttp://docs.python.org will be automaticallyredirected tohttp://docs.python.org/3/, but links deeper inthe version-specific hierarchy, such as tohttp://docs.python.org/library/os, will instead be redirected toa Python 2 specific link such ashttp://docs.python.org/2/library/os.
The specific subpaths which will be redirected to explicitly qualifiedpaths for the Python 2 docs are:
/c-api//distutils//extending//faq//howto//library//reference//tutorial//using//whatsnew//about.html/bugs.html/contents.html/copyright.html/license.html/genindex.html/glossary.html/py-modindex.html/search.htmlThe existing/py3k/ subpath will be redirected to the new/3/subpath.
With this scheme, the following URLs would be presented to users afterresolution of any aliasing and rewriting rules:
http://docs.python.org/x/*http://docs.python.org/x.y/*http://docs.python.org/dev/*http://docs.python.org/release/x.y.z/*http://docs.python.org/devguideThe/x/ URLs mean “give me the latest documentation for a releasedversion in this release series”. It will draw the documentation from therelevant maintenance branch in source control (this will always be the2.7 branch for Python 2 and is currently 3.3 for Python 3). Differencesrelative to previous versions in the release series will be availablethrough “version added” and “version changed” markers.
The/x.y/ URLs mean “give me the latest documentation for this release”.It will draw the documentation from the relevant maintenance branch insource control (or the default branch for the currently in developmentversion). It differs from the status quo in that the URLs willactually remain available in the user’s browser for easy copy and pasting.(Currently, references to specific versions that are not the latest in theirrelease series will resolve to a stable URL for a specific maintenanceversion in the “release” hierarchy, while the current latest version in therelease series resolves to the release series URL. This makes it hard to geta “latest version specific URL”, since it is always necessary to constructthem manually).
The/dev/ URL means the documentation for the default branch in sourcecontrol.
The/release/x.y.x/ URLs will refer to the documentation of thosereleases, exactly as it was at the time of the release.
The developer’s guide is not version specific, and thus retains its ownstable/devguide/ URL.
There is some desire to switch the unqualified references to mean Python 3as a sign of confidence in Python 3. Such a move would either break a lot ofthings, or else involve an awful lot of work toavoid breaking things.
I believe we can get much the same effect without breaking the world by:
http://docs.python.org tohttp://docs.python.org/3.xMost importantly, because this scheme doesn’t alter the behaviour of anyexisting deep links, it could be implemented with a significantly shorterwarning period than would be required for a scheme that risked breakingdeep links, or started to redirect unqualified links to Python 3. Theonly part of the scheme which would require any warning at all is thestep of redirecting the “http://docs.python.org/” landing page to thePython 3.3 documentation.
Namespaces are one honking great idea - let’s do more of those.
Note that the approach described in this PEP gives two ways to access thecontent of the default branch: as/dev/ or using the appropriate/x.y/ reference. This is deliberate, as the default branch is referencedfor two different purposes:
/x.y/ URL is appropriate)/dev/ URL isappropriate)The URLs on docs.python.org are controlled by the python.org infrastructureteam rather than through the CPython source repo, so acceptance andimplementation of the ideas in this PEP will be up to the team.
This document has been placed in the public domain.
Source:https://github.com/python/peps/blob/main/peps/pep-0430.rst
Last modified:2025-02-01 08:59:27 GMT