Commits

Anonymous committed 9c81c3b

Finished the "porting to 3.0" section. Had to add a label to
howto/cporting.rst.

Comments (0)

Files changed (2)

Doc/howto/cporting.rst

 .. highlightlang:: c
 
+.. _cporting-howto:
+
 ********************************
 Porting Extension Modules to 3.0
 ********************************

Doc/whatsnew/3.0.rst

 Library Changes
 ===============
 
+Due to time constraints, this document does not exhaustively cover
+the very extensive changes to the library.  
+
 XXX Brief overview of what's changed in the library.
 
 * :pep:`3108`: stdlib reorganization.
 Porting To Python 3.0
 =====================
 
-This section lists previously described changes that may require
-changes to your code:
+For porting existing Python 2.5 or 2.6 source code to Python 3.0, the
+best strategy is the following:
 
-* Everything is all in the details!
+0. (Prerequisite:) Start with excellent test coverage.
 
-* Developers can include :file:`intobject.h` after :file:`Python.h` for
-  some ``PyInt_`` aliases.
+1. Port to Python 2.6.  This should be no more work than the average
+   port from Python 2.x to Python 2.(x+1).  Make sure all your tests
+   pass.
 
-* XXX Mention 2to3.
+2. (Still using 2.6:) Turn on the :option:`-3` command line switch.
+   This enables warnings about features that will be removed (or
+   change) in 3.0.  Run your test suite again, and fix code that you
+   get warnings about until there are no warnings left, and all your
+   tests still pass.
 
-* XXX Reference external doc about porting extensions?
+3. Run the ``2to3`` source-to-source translator over your source code
+   tree.  (See :ref:`2to3-reference` for more on this tool.)  Run the
+   result of the translation under Python 3.0.  Manually fix up any
+   remaining issues, fixing problems until all tests pass again.
+
+It is not recommended to try to write source code that runs unchanged
+under both Python 2.6 and 3.0; you'd have to use a very contorted
+coding style, e.g. avoiding :keyword:`print` statements, metaclasses,
+and much more.  If you are maintaining a library that needs to support
+both Python 2.6 and Python 3.0, the best approach is to modify step 3
+above by editing the 2.6 version of the source code and running the
+``2to3`` translator again, rather than editing the 3.0 version of the
+source code.
+
+For porting C extensions to Python 3.0, please see :ref:`cporting-howto`.
 
 .. ======================================================================
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.