[Python-3000] pre-PEP: Process for reviewing/improving stdlib modules in 3.0

[Guido van Rossum]

I didn't see any comments on this PEP. Is there consensus that this is
the way we should do it? I'm not sure that the order in which the
steps are to be carried out is all that important, nor that it's
necessary to do this in the same order for all modules, but otherwise
the only thing that bugs me is the reference to the great stdlib
renaming (which I'm not sure is such a great idea). I expect that some
of the goals (especially test coverage) are too ambitious, but it's
worth at least aspiring to great works!

BTW we need a procedure for assigning PEP numbers > 3000. Once it's
clear whether a PEP is a meta-pep or a feature proposal (usually
pretty clear) IMO the author can just pick the next available number
in the appropriate range (3001-3099 for meta-PEPs, 3100-3999 for
feature-PEPs) and check it in. Perhaps that process is an issue for
the meta-meta-PEP, PEP 3000? (Also, since the current PEP 3000 mostly
focuses on features, perhaps it ought to be torm apart into pieces
that are each given their own feature PEP?)

--Guido

On 4/2/06, Georg Brandl <g.brandl at gmx.net> wrote:
> PEP: XXX
> Title: Procedure for changing standard library modules
> Version: $Revision$
> Last-Modified: $Date$
> Author: Georg Brandl <g.brandl at gmx.net>
> Status: Draft
> Type: Informational
> Content-Type: text/x-rst
> Created: 02-Apr-2006
>
>
> Abstract
> ========
>
> This PEP describes the 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.
>
>
> Step 1: 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.
>
>
> Step 2: Renaming modules
> ========================
>
> Aside from a "great stdlib renaming" introducing a hierarchic library
> namespace or a top-level package from which to import standard modules,
> 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 possi-
> bility to rename those modules to 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.
>
>
> Step 3: 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.
>
>
> Step 4: 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.
>
>
> Step 5: 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.
>
>
> Step 6: 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.
>
>
> Step 7: 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
> ==========
>
> TBD
>
> Copyright
> =========
>
> This document has been placed in the public domain.
>
> _______________________________________________
> Python-3000 mailing list
> Python-3000 at python.org
> http://mail.python.org/mailman/listinfo/python-3000
> Unsubscribe: http://mail.python.org/mailman/options/python-3000/guido%40python.org
>


--
--Guido van Rossum (home page: http://www.python.org/~guido/)