232 lines
14 KiB
HTML
232 lines
14 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 3001 – Procedure for reviewing and improving standard library modules | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-3001/">
|
||
<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 3001 – Procedure for reviewing and improving standard library modules | peps.python.org'>
|
||
<meta property="og:description" content="This PEP describes a procedure for reviewing and improving standard library modules, especially those written in Python, making them ready for Python 3000. There can be different steps of refurbishing, each of which is described in a section below. Of...">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-3001/">
|
||
<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 a procedure for reviewing and improving standard library modules, especially those written in Python, making them ready for Python 3000. There can be different steps of refurbishing, each of which is described in a section below. Of...">
|
||
<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 3001</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 3001 – Procedure for reviewing and improving standard library modules</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Georg Brandl <georg at python.org></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Removed from consideration by sponsor or authors">Withdrawn</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">05-Apr-2006</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><p></p></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="#removal-of-obsolete-modules">Removal of obsolete modules</a></li>
|
||
<li><a class="reference internal" href="#renaming-modules">Renaming modules</a></li>
|
||
<li><a class="reference internal" href="#code-cleanup">Code cleanup</a></li>
|
||
<li><a class="reference internal" href="#enhancement-of-test-and-documentation-coverage">Enhancement of test and documentation coverage</a></li>
|
||
<li><a class="reference internal" href="#unification-of-module-metadata">Unification of module metadata</a></li>
|
||
<li><a class="reference internal" href="#backwards-incompatible-bug-fixes">Backwards incompatible bug fixes</a></li>
|
||
<li><a class="reference internal" href="#interface-changes">Interface changes</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 a procedure for reviewing and improving standard
|
||
library modules, especially those written in Python, making them ready
|
||
for Python 3000. There can be different steps of refurbishing, each
|
||
of which is described in a section below. Of course, not every step
|
||
has to be performed for every module.</p>
|
||
</section>
|
||
<section id="removal-of-obsolete-modules">
|
||
<h2><a class="toc-backref" href="#removal-of-obsolete-modules" role="doc-backlink">Removal of obsolete modules</a></h2>
|
||
<p>All modules marked as deprecated in 2.x versions should be removed for
|
||
Python 3000. The same applies to modules which are seen as obsolete today,
|
||
but are too widely used to be deprecated or removed. Python 3000 is the
|
||
big occasion to get rid of them.</p>
|
||
<p>There will have to be a document listing all removed modules, together
|
||
with information on possible substitutes or alternatives. This
|
||
information will also have to be provided by the python3warn.py porting
|
||
helper script mentioned in PEP XXX.</p>
|
||
</section>
|
||
<section id="renaming-modules">
|
||
<h2><a class="toc-backref" href="#renaming-modules" role="doc-backlink">Renaming modules</a></h2>
|
||
<p>There are proposals for a “great stdlib renaming” introducing a hierarchic
|
||
library namespace or a top-level package from which to import standard
|
||
modules. That possibility aside, some modules’ names are known to have
|
||
been chosen unwisely, a mistake which could never be corrected in the 2.x
|
||
series. Examples are names like “StringIO” or “Cookie”. For Python 3000,
|
||
there will be the possibility to give those modules less confusing and
|
||
more conforming names.</p>
|
||
<p>Of course, each rename will have to be stated in the documentation of
|
||
the respective module and perhaps in the global document of Step 1.
|
||
Additionally, the python3warn.py script will recognize the old module
|
||
names and notify the user accordingly.</p>
|
||
<p>If the name change is made in time for another release of the Python 2.x
|
||
series, it is worth considering to introduce the new name in the 2.x
|
||
branch to ease transition.</p>
|
||
</section>
|
||
<section id="code-cleanup">
|
||
<h2><a class="toc-backref" href="#code-cleanup" role="doc-backlink">Code cleanup</a></h2>
|
||
<p>As most library modules written in Python have not been touched except
|
||
for bug fixes, following the policy of never changing a running system,
|
||
many of them may contain code that is not up to the newest language
|
||
features and could be rewritten in a more concise, modern Python.</p>
|
||
<p>PyChecker should run cleanly over the library. With a carefully tuned
|
||
configuration file, PyLint should also emit as few warnings as possible.</p>
|
||
<p>As long as these changes don’t change the module’s interface and behavior,
|
||
no documentation updates are necessary.</p>
|
||
</section>
|
||
<section id="enhancement-of-test-and-documentation-coverage">
|
||
<h2><a class="toc-backref" href="#enhancement-of-test-and-documentation-coverage" role="doc-backlink">Enhancement of test and documentation coverage</a></h2>
|
||
<p>Code coverage by unit tests varies greatly between modules. Each test
|
||
suite should be checked for completeness, and the remaining classic tests
|
||
should be converted to PyUnit (or whatever new shiny testing framework
|
||
comes with Python 3000, perhaps py.test?).</p>
|
||
<p>It should also be verified that each publicly visible function has a
|
||
meaningful docstring which ideally contains several doctests.</p>
|
||
<p>No documentation changes are necessary for enhancing test coverage.</p>
|
||
</section>
|
||
<section id="unification-of-module-metadata">
|
||
<h2><a class="toc-backref" href="#unification-of-module-metadata" role="doc-backlink">Unification of module metadata</a></h2>
|
||
<p>This is a small and probably not very important step. There have been
|
||
various attempts at providing author, version and similar metadata in
|
||
modules (such as a “__version__” global). Those could be standardized
|
||
and used throughout the library.</p>
|
||
<p>No documentation changes are necessary for this step, too.</p>
|
||
</section>
|
||
<section id="backwards-incompatible-bug-fixes">
|
||
<h2><a class="toc-backref" href="#backwards-incompatible-bug-fixes" role="doc-backlink">Backwards incompatible bug fixes</a></h2>
|
||
<p>Over the years, many bug reports have been filed which complained about
|
||
bugs in standard library modules, but have subsequently been closed as
|
||
“Won’t fix” since a fix would have introduced a major incompatibility
|
||
which was not acceptable in the Python 2.x series. In Python 3000, the
|
||
fix can be applied if the interface per se is still acceptable.</p>
|
||
<p>Each slight behavioral change caused by such fixes must be mentioned in
|
||
the documentation, perhaps in a “Changed in Version 3.0” paragraph.</p>
|
||
</section>
|
||
<section id="interface-changes">
|
||
<h2><a class="toc-backref" href="#interface-changes" role="doc-backlink">Interface changes</a></h2>
|
||
<p>The last and most disruptive change is the overhaul of a module’s public
|
||
interface. If a module’s interface is to be changed, a justification
|
||
should be made beforehand, or a PEP should be written.</p>
|
||
<p>The change must be fully documented as “New in Version 3.0”, and the
|
||
python3warn.py script must know about it.</p>
|
||
</section>
|
||
<section id="references">
|
||
<h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2>
|
||
<p>None yet.</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-3001.rst">https://github.com/python/peps/blob/main/peps/pep-3001.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-3001.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="#removal-of-obsolete-modules">Removal of obsolete modules</a></li>
|
||
<li><a class="reference internal" href="#renaming-modules">Renaming modules</a></li>
|
||
<li><a class="reference internal" href="#code-cleanup">Code cleanup</a></li>
|
||
<li><a class="reference internal" href="#enhancement-of-test-and-documentation-coverage">Enhancement of test and documentation coverage</a></li>
|
||
<li><a class="reference internal" href="#unification-of-module-metadata">Unification of module metadata</a></li>
|
||
<li><a class="reference internal" href="#backwards-incompatible-bug-fixes">Backwards incompatible bug fixes</a></li>
|
||
<li><a class="reference internal" href="#interface-changes">Interface changes</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-3001.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> |