224 lines
13 KiB
HTML
224 lines
13 KiB
HTML
|
||
<!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 3002 – Procedure for Backwards-Incompatible Changes | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-3002/">
|
||
<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 3002 – Procedure for Backwards-Incompatible Changes | peps.python.org'>
|
||
<meta property="og:description" content="This PEP describes the procedure for changes to Python that are backwards-incompatible between the Python 2.X series and Python 3000. All such changes must be documented by an appropriate Python 3000 PEP and must be accompanied by code that can identify...">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-3002/">
|
||
<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 describes the procedure for changes to Python that are backwards-incompatible between the Python 2.X series and Python 3000. All such changes must be documented by an appropriate Python 3000 PEP and must be accompanied by code that can identify...">
|
||
<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 3002</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 3002 – Procedure for Backwards-Incompatible Changes</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Steven Bethard <steven.bethard at gmail.com></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Normative PEP describing or proposing a change to a Python community process, workflow or governance">Process</abbr></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">27-Mar-2006</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd">27-Mar-2006, 13-Apr-2006</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="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#python-enhancement-proposals">Python Enhancement Proposals</a></li>
|
||
<li><a class="reference internal" href="#identifying-problematic-code">Identifying Problematic Code</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 describes the procedure for changes to Python that are
|
||
backwards-incompatible between the Python 2.X series and Python 3000.
|
||
All such changes must be documented by an appropriate Python 3000 PEP
|
||
and must be accompanied by code that can identify when pieces of
|
||
Python 2.X code may be problematic in Python 3000.</p>
|
||
</section>
|
||
<section id="rationale">
|
||
<h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2>
|
||
<p>Python 3000 will introduce a number of backwards-incompatible changes
|
||
to Python, mainly to streamline the language and to remove some
|
||
previous design mistakes. But Python 3000 is not intended to be a new
|
||
and completely different language from the Python 2.X series, and it
|
||
is expected that much of the Python user community will make the
|
||
transition to Python 3000 when it becomes available.</p>
|
||
<p>To encourage this transition, it is crucial to provide a clear and
|
||
complete guide on how to upgrade Python 2.X code to Python 3000 code.
|
||
Thus, for any backwards-incompatible change, two things are required:</p>
|
||
<ul class="simple">
|
||
<li>An official Python Enhancement Proposal (PEP)</li>
|
||
<li>Code that can identify pieces of Python 2.X code that may be
|
||
problematic in Python 3000</li>
|
||
</ul>
|
||
</section>
|
||
<section id="python-enhancement-proposals">
|
||
<h2><a class="toc-backref" href="#python-enhancement-proposals" role="doc-backlink">Python Enhancement Proposals</a></h2>
|
||
<p>Every backwards-incompatible change must be accompanied by a PEP.
|
||
This PEP should follow the usual PEP guidelines and explain the
|
||
purpose and reasoning behind the backwards incompatible change. In
|
||
addition to the usual PEP sections, all PEPs proposing
|
||
backwards-incompatible changes must include an additional section:
|
||
Compatibility Issues. This section should describe what is backwards
|
||
incompatible about the proposed change to Python, and the major sorts
|
||
of breakage to be expected.</p>
|
||
<p>While PEPs must still be evaluated on a case-by-case basis, a PEP may
|
||
be inappropriate for Python 3000 if its Compatibility Issues section
|
||
implies any of the following:</p>
|
||
<ul>
|
||
<li>Most or all instances of a Python 2.X construct are incorrect in
|
||
Python 3000, and most or all instances of the Python 3000 construct
|
||
are incorrect in Python 2.X.<p>So for example, changing the meaning of the for-loop else-clause
|
||
from “executed when the loop was not broken out of” to “executed
|
||
when the loop had zero iterations” would mean that all Python 2.X
|
||
for-loop else-clauses would be broken, and there would be no way to
|
||
use a for-loop else-clause in a Python-3000-appropriate manner.
|
||
Thus a PEP for such an idea would likely be rejected.</p>
|
||
</li>
|
||
<li>Many instances of a Python 2.X construct are incorrect in Python
|
||
3000 and the PEP fails to demonstrate real-world use-cases for the
|
||
changes.<p>Backwards incompatible changes are allowed in Python 3000, but not
|
||
to excess. A PEP that proposes backwards-incompatible changes
|
||
should provide good examples of code that visibly benefits from the
|
||
changes.</p>
|
||
</li>
|
||
</ul>
|
||
<p>PEP-writing is time-consuming, so when a number of
|
||
backwards-incompatible changes are closely related, they should be
|
||
proposed in the same PEP. Such PEPs will likely have longer
|
||
Compatibility Issues sections, however, since they must now describe
|
||
the sorts of breakage expected from <em>all</em> the proposed changes.</p>
|
||
</section>
|
||
<section id="identifying-problematic-code">
|
||
<h2><a class="toc-backref" href="#identifying-problematic-code" role="doc-backlink">Identifying Problematic Code</a></h2>
|
||
<p>In addition to the PEP requirement, backwards incompatible changes to
|
||
Python must also be accompanied by code to issue warnings for pieces
|
||
of Python 2.X code that will behave differently in Python 3000. Such
|
||
warnings will be enabled in Python 2.X using a new command-line
|
||
switch: -3. All backwards incompatible changes should be
|
||
accompanied by a patch for Python 2.X that, when -3 is
|
||
specified, issues warnings for each construct that is being changed.</p>
|
||
<p>For example, if <code class="docutils literal notranslate"><span class="pre">dict.keys()</span></code> returns an iterator in Python 3000,
|
||
the patch to the Python 2.X branch should do something like:</p>
|
||
<blockquote>
|
||
<div>If -3 was specified, change <code class="docutils literal notranslate"><span class="pre">dict.keys()</span></code> to return a
|
||
subclass of <code class="docutils literal notranslate"><span class="pre">list</span></code> that issues warnings whenever you use any
|
||
methods other than <code class="docutils literal notranslate"><span class="pre">__iter__()</span></code>.</div></blockquote>
|
||
<p>Such a patch would mean that warnings are only issued when features
|
||
that will not be present in Python 3000 are used, and almost all
|
||
existing code should continue to work. (Code that relies on
|
||
<code class="docutils literal notranslate"><span class="pre">dict.keys()</span></code> always returning a <code class="docutils literal notranslate"><span class="pre">list</span></code> and not a subclass should
|
||
be pretty much non-existent.)</p>
|
||
</section>
|
||
<section id="references">
|
||
<h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2>
|
||
<p>TBD</p>
|
||
</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-3002.rst">https://github.com/python/peps/blob/main/peps/pep-3002.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-3002.rst">2023-09-09 17:39:29 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="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#python-enhancement-proposals">Python Enhancement Proposals</a></li>
|
||
<li><a class="reference internal" href="#identifying-problematic-code">Identifying Problematic Code</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-3002.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> |