121 lines
4.0 KiB
Plaintext
121 lines
4.0 KiB
Plaintext
|
PEP: 3001
|
||
|
|
Title: Procedure for reviewing and improving standard library modules
|
||
|
|
Version: $Revision$
|
||
|
|
Last-Modified: $Date$
|
||
|
|
Author: Georg Brandl <g.brandl@gmx.net>
|
||
|
|
Status: Draft
|
||
|
|
Type: Process
|
||
|
|
Content-Type: text/x-rst
|
||
|
|
Created: 05-Apr-2006
|
||
|
|
|
||
|
|
|
||
|
|
Abstract
|
||
|
|
========
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
Removal of obsolete modules
|
||
|
|
===========================
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
There will have to be a document listing all removed modules, together
|
||
|
|
with information on possible substitutes or alternatives. This infor-
|
||
|
|
mation will also have to be provided by the python3warn.py porting
|
||
|
|
helper script mentioned in PEP XXX.
|
||
|
|
|
||
|
|
|
||
|
|
Renaming modules
|
||
|
|
================
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
Code cleanup
|
||
|
|
============
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
As long as these changes don't change the module's interface and behavior,
|
||
|
|
no documentation updates are necessary.
|
||
|
|
|
||
|
|
|
||
|
|
Enhancement of test coverage
|
||
|
|
============================
|
||
|
|
|
||
|
|
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?).
|
||
|
|
|
||
|
|
No documentation changes are necessary for this step.
|
||
|
|
|
||
|
|
|
||
|
|
Unification of module metadata
|
||
|
|
==============================
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
No documentation changes are necessary for this step, too.
|
||
|
|
|
||
|
|
|
||
|
|
Backwards incompatible bug fixes
|
||
|
|
================================
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
Each slight behavioral change caused by such fixes must be mentioned in
|
||
|
|
the documentation, perhaps in a "Changed in Version 3.0" paragraph.
|
||
|
|
|
||
|
|
|
||
|
|
Interface changes
|
||
|
|
=================
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
The change must be fully documented as "New in Version 3.0", and the
|
||
|
|
python3warn.py script must know about it.
|
||
|
|
|
||
|
|
|
||
|
|
References
|
||
|
|
==========
|
||
|
|
|
||
|
|
None yet.
|
||
|
|
|
||
|
|
|
||
|
|
Copyright
|
||
|
|
=========
|
||
|
|
|
||
|
|
This document has been placed in the public domain.
|