CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 430 – Migrating to Python 3 as the default online documentation | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0430/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 430 – Migrating to Python 3 as the default online documentation | peps.python.org'> <meta property="og:description" content="This PEP proposes a strategy for migrating the default version of the Python documentation presented to users of Python when accessing docs.python.org from 2.7 to Python 3.3."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0430/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP proposes a strategy for migrating the default version of the Python documentation presented to users of Python when accessing docs.python.org from 2.7 to Python 3.3."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 430</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 430 – Migrating to Python 3 as the default online documentation</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Alyssa Coghlan <ncoghlan at gmail.com></dd> <dt class="field-even">BDFL-Delegate<span class="colon">:</span></dt> <dd class="field-even">Georg Brandl</dd> <dt class="field-odd">Status<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-even">Type<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Non-normative PEP containing background, guidelines or other information relevant to the Python ecosystem">Informational</abbr></dd> <dt class="field-odd">Created<span class="colon">:</span></dt> <dd class="field-odd">27-Oct-2012</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#background">Background</a></li> <li><a class="reference internal" href="#key-concerns">Key Concerns</a><ul> <li><a class="reference internal" href="#don-t-confuse-beginners">Don’t Confuse Beginners</a></li> <li><a class="reference internal" href="#don-t-break-useful-resources">Don’t Break Useful Resources</a></li> </ul> </li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#presented-urls">Presented URLs</a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p>This PEP proposes a strategy for migrating the default version of the Python documentation presented to users of Python when accessing docs.python.org from 2.7 to Python 3.3.</p> <p>It proposes a backwards compatible scheme that preserves the meaning of existing deep links in to the Python 2 documentation, while still presenting the Python 3 documentation by default, and presenting the Python 2 and 3 documentation in a way that avoids making the Python 3 documentation look like a second-class citizen.</p> </section> <section id="background"> <h2><a class="toc-backref" href="#background" role="doc-backlink">Background</a></h2> <p>With the transition of the overall Python ecosystem from Python 2 to Python 3 still in progress, one question which arises periodically <a class="footnote-reference brackets" href="#id4" id="id1">[1]</a>, <a class="footnote-reference brackets" href="#id5" id="id2">[2]</a> is when and how to handle the change from providing the Python 2 documentation as the default version displayed at the docs.python.org root URL to providing the Python 3 documentation.</p> </section> <section id="key-concerns"> <h2><a class="toc-backref" href="#key-concerns" role="doc-backlink">Key Concerns</a></h2> <p>There are a couple of key concerns that any migration proposal needs to address.</p> <section id="don-t-confuse-beginners"> <h3><a class="toc-backref" href="#don-t-confuse-beginners" role="doc-backlink">Don’t Confuse Beginners</a></h3> <p>Many beginners learn Python through third party resources. These resources, not all of which are online resources, may reference in to the python.org online documentation for additional background and details.</p> <p>Importantly, even when the online documentation is updated, the “version added” and “version changed” tags usually provide enough information for users to adjust appropriately for the specific version they are using.</p> <p>While deep links in to the python.org documentation may occasionally break within the Python 2 series, this is very rare.</p> <p>Migrating to Python 3 is a very different matter. Many links would break due to renames and removals, and the “version added” and “version changed” information for the Python 2 series is completely absent.</p> </section> <section id="don-t-break-useful-resources"> <h3><a class="toc-backref" href="#don-t-break-useful-resources" role="doc-backlink">Don’t Break Useful Resources</a></h3> <p>There are many useful Python resources out there, such as the mailing list archives on python.org and question-and-answer sites like Stack Overflow, where links are highly unlikely to be updated, no matter how much notice is provided.</p> <p>Old posts and answers to questions all currently link to docs.python.org expecting to get the Python 2 documentation at unqualified URLs. Links from answers that relate to Python 3 are explicitly qualified with <code class="docutils literal notranslate"><span class="pre">/py3k/</span></code> in the path component.</p> </section> </section> <section id="proposal"> <h2><a class="toc-backref" href="#proposal" role="doc-backlink">Proposal</a></h2> <p>This PEP (based on an idea originally put forward back in May <a class="footnote-reference brackets" href="#id6" id="id3">[3]</a>) is to <em>not migrate</em> the Python 2 specific deep links at all, and instead adopt a scheme where all URLs presented to users on docs.python.org are qualified appropriately with the relevant release series.</p> <p>Visitors to the root URL at <code class="docutils literal notranslate"><span class="pre">http://docs.python.org</span></code> will be automatically redirected to <code class="docutils literal notranslate"><span class="pre">http://docs.python.org/3/</span></code>, but links deeper in the version-specific hierarchy, such as to <code class="docutils literal notranslate"><span class="pre">http://docs.python.org/library/os</span></code>, will instead be redirected to a Python 2 specific link such as <code class="docutils literal notranslate"><span class="pre">http://docs.python.org/2/library/os</span></code>.</p> <p>The specific subpaths which will be redirected to explicitly qualified paths for the Python 2 docs are:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">/c-api/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/distutils/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/extending/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/faq/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/howto/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/library/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/reference/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/tutorial/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/using/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/whatsnew/</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/about.html</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/bugs.html</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/contents.html</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/copyright.html</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/license.html</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/genindex.html</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/glossary.html</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/py-modindex.html</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">/search.html</span></code></li> </ul> <p>The existing <code class="docutils literal notranslate"><span class="pre">/py3k/</span></code> subpath will be redirected to the new <code class="docutils literal notranslate"><span class="pre">/3/</span></code> subpath.</p> <section id="presented-urls"> <h3><a class="toc-backref" href="#presented-urls" role="doc-backlink">Presented URLs</a></h3> <p>With this scheme, the following URLs would be presented to users after resolution of any aliasing and rewriting rules:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">http://docs.python.org/x/*</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">http://docs.python.org/x.y/*</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">http://docs.python.org/dev/*</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">http://docs.python.org/release/x.y.z/*</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">http://docs.python.org/devguide</span></code></li> </ul> <p>The <code class="docutils literal notranslate"><span class="pre">/x/</span></code> URLs mean “give me the latest documentation for a released version in this release series”. It will draw the documentation from the relevant maintenance branch in source control (this will always be the 2.7 branch for Python 2 and is currently 3.3 for Python 3). Differences relative to previous versions in the release series will be available through “version added” and “version changed” markers.</p> <p>The <code class="docutils literal notranslate"><span class="pre">/x.y/</span></code> URLs mean “give me the latest documentation for this release”. It will draw the documentation from the relevant maintenance branch in source control (or the default branch for the currently in development version). It differs from the status quo in that the URLs will actually remain available in the user’s browser for easy copy and pasting. (Currently, references to specific versions that are not the latest in their release series will resolve to a stable URL for a specific maintenance version in the “release” hierarchy, while the current latest version in the release series resolves to the release series URL. This makes it hard to get a “latest version specific URL”, since it is always necessary to construct them manually).</p> <p>The <code class="docutils literal notranslate"><span class="pre">/dev/</span></code> URL means the documentation for the default branch in source control.</p> <p>The <code class="docutils literal notranslate"><span class="pre">/release/x.y.x/</span></code> URLs will refer to the documentation of those releases, exactly as it was at the time of the release.</p> <p>The developer’s guide is not version specific, and thus retains its own stable <code class="docutils literal notranslate"><span class="pre">/devguide/</span></code> URL.</p> </section> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <p>There is some desire to switch the unqualified references to mean Python 3 as a sign of confidence in Python 3. Such a move would either break a lot of things, or else involve an awful lot of work to <em>avoid</em> breaking things.</p> <p>I believe we can get much the same effect without breaking the world by:</p> <ol class="arabic simple"> <li>Deprecating the use of unqualified references to the online documentation (while promising to preserve the meaning of such references indefinitely)</li> <li>Updating all python.org and python-dev controlled links to use qualified references (excluding archived email)</li> <li>Redirecting visitors to the root of <code class="docutils literal notranslate"><span class="pre">http://docs.python.org</span></code> to <code class="docutils literal notranslate"><span class="pre">http://docs.python.org/3.x</span></code></li> </ol> <p>Most importantly, because this scheme doesn’t alter the behaviour of any existing deep links, it could be implemented with a significantly shorter warning period than would be required for a scheme that risked breaking deep links, or started to redirect unqualified links to Python 3. The only part of the scheme which would require any warning at all is the step of redirecting the “<a class="reference external" href="http://docs.python.org/">http://docs.python.org/</a>” landing page to the Python 3.3 documentation.</p> <p>Namespaces are one honking great idea - let’s do more of those.</p> <p>Note that the approach described in this PEP gives two ways to access the content of the default branch: as <code class="docutils literal notranslate"><span class="pre">/dev/</span></code> or using the appropriate <code class="docutils literal notranslate"><span class="pre">/x.y/</span></code> reference. This is deliberate, as the default branch is referenced for two different purposes:</p> <ul class="simple"> <li>to provide additional information when discussing an upcoming feature of the next release (a <code class="docutils literal notranslate"><span class="pre">/x.y/</span></code> URL is appropriate)</li> <li>to provide a stable destination for developers to access the documentation of the next feature release, regardless of the version (a <code class="docutils literal notranslate"><span class="pre">/dev/</span></code> URL is appropriate)</li> </ul> </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> <p>The URLs on docs.python.org are controlled by the python.org infrastructure team rather than through the CPython source repo, so acceptance and implementation of the ideas in this PEP will be up to the team.</p> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id4" role="doc-footnote"> <dt class="label" id="id4">[<a href="#id1">1</a>]</dt> <dd>May 2012 discussion (<a class="reference external" href="https://mail.python.org/pipermail/python-dev/2012-May/119524.html">https://mail.python.org/pipermail/python-dev/2012-May/119524.html</a>)</aside> <aside class="footnote brackets" id="id5" role="doc-footnote"> <dt class="label" id="id5">[<a href="#id2">2</a>]</dt> <dd>October 2012 discussion (<a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2012-October/017406.html">https://mail.python.org/pipermail/python-ideas/2012-October/017406.html</a>)</aside> <aside class="footnote brackets" id="id6" role="doc-footnote"> <dt class="label" id="id6">[<a href="#id3">3</a>]</dt> <dd>Using a “/latest/” path prefix (<a class="reference external" href="https://mail.python.org/pipermail/python-dev/2012-May/119567.html">https://mail.python.org/pipermail/python-dev/2012-May/119567.html</a>)</aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document has been placed in the public domain.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0430.rst">https://github.com/python/peps/blob/main/peps/pep-0430.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0430.rst">2023-10-11 12:05:51 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#background">Background</a></li> <li><a class="reference internal" href="#key-concerns">Key Concerns</a><ul> <li><a class="reference internal" href="#don-t-confuse-beginners">Don’t Confuse Beginners</a></li> <li><a class="reference internal" href="#don-t-break-useful-resources">Don’t Break Useful Resources</a></li> </ul> </li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#presented-urls">Presented URLs</a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0430.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>