diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/howto/cporting.rst | 2 | ||||
| -rw-r--r-- | Doc/whatsnew/3.0.rst | 36 |
2 files changed, 31 insertions, 7 deletions
diff --git a/Doc/howto/cporting.rst b/Doc/howto/cporting.rst index 3451f5c..3102fb5 100644 --- a/Doc/howto/cporting.rst +++ b/Doc/howto/cporting.rst @@ -1,5 +1,7 @@ .. highlightlang:: c +.. _cporting-howto: + ******************************** Porting Extension Modules to 3.0 ******************************** diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst index 5803cd8..51dff47 100644 --- a/Doc/whatsnew/3.0.rst +++ b/Doc/whatsnew/3.0.rst @@ -426,6 +426,9 @@ consulted for longer descriptions. 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. @@ -778,16 +781,35 @@ XXX Some of the more notable changes are: 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: + +0. (Prerequisite:) Start with excellent test coverage. + +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. -* Everything is all in the details! +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. -* Developers can include :file:`intobject.h` after :file:`Python.h` for - some ``PyInt_`` aliases. +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. -* XXX Mention 2to3. +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. -* XXX Reference external doc about porting extensions? +For porting C extensions to Python 3.0, please see :ref:`cporting-howto`. .. ====================================================================== |