[Python-checkins] r63107 - peps/trunk/pep-3108.txt

[brett.cannon]

Author: brett.cannon
Date: Mon May 12 01:24:02 2008
New Revision: 63107

Log:
Try to outline the steps necessary to rename a module.


Modified:
   peps/trunk/pep-3108.txt

Modified: peps/trunk/pep-3108.txt
==============================================================================
--- peps/trunk/pep-3108.txt	(original)
+++ peps/trunk/pep-3108.txt	Mon May 12 01:24:02 2008
@@ -935,7 +935,7 @@
     ``test.test_support.import_module(name, deprecated=True)``.
 
 #. Check in the change w/ appropriate ``Misc/NEWS`` entry (**block**
-   the checkin in ``py3k``!).
+   this checkin in ``py3k``!).
 
 #. Update this PEP noting that the 2.6 step is done.
 
@@ -943,23 +943,8 @@
 Renaming of modules
 -------------------
 
-Stub modules will be created which have the original names.  They
-will reside in a stdlib directory similar to the defunct ``lib-old``
-directory.  This facility prevents naming conflicts on
-case-insensitive filesystems where only the case of a module's name
-changed.
-
-The stub modules will import the module code based on the new names::
-
-  from sys import modules
-  import new_name
-  modules[__name__] = new_name
-
-As with modules to be removed in 3.0 but not in 2.x,
-``DeprecationWarning`` will be raised using the ``warnings.warn3k()``
-function.
-
-Support in the 2to3 refactoring tool for renames will also be used
+Support in the 2to3 refactoring tool for renames will be used to help
+people transition to new module names
 [#2to3]_.  Import statements will be rewritten so that only the import
 statement and none of the rest of the code needs to be touched.  This
 will be accomplished by using the ``as`` keyword in import statements
@@ -970,6 +955,53 @@
 example of how to approach this.
 
 
+Python 2.6
+//////////
+
+#. Use ``svn move`` to rename the module.
+
+#. Create a stub module in ``Lib/lib-old``::
+
+     from warnings import warnpy3k
+     warnpy3k("The XXX module has been renamed to XXX in Python 3.0",
+              stacklevel=2)
+
+     from sys import modules
+     import XXX
+     modules[__name__] = XXX
+
+#. Add a test to ``test_py3kwarn``.
+
+#. Add a ``warning`` directive to the module's documentation.
+
+#. Add an entry in ``Misc/NEWS``.
+
+#. Commit the changes (**block** in py3k).
+
+#. Update all import statements in the stdlib to use the new name.
+
+#. Rename the module in the documentation (both its own and all
+   references).
+
+#. Commit the changes (this checkin should be allowed to propagate to py3k).
+
+#. Add stub entries in the documentation for the old names which
+   lists the module as deprecated under that name and points to the
+   new name (see the module removal steps on the required steps).
+
+
+Python 3.0
+//////////
+
+#. Use ``svn move`` to rename the module.
+
+#. Merge appropriate checkins from 2.6.
+
+#. Add an entry in ``Misc/NEWS``.
+
+#. Commit the changes.
+
+
 Open Issues
 ===========