Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
C
cpython
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
Kirill Smelkov
cpython
Commits
b7e6b895
Commit
b7e6b895
authored
Mar 09, 2013
by
Brett Cannon
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Touch up the Python 2 to 3 porting guide
parent
c2d90fb3
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
48 additions
and
15 deletions
+48
-15
Doc/howto/pyporting.rst
Doc/howto/pyporting.rst
+46
-15
Misc/NEWS
Misc/NEWS
+2
-0
No files found.
Doc/howto/pyporting.rst
View file @
b7e6b895
...
@@ -21,21 +21,21 @@ Porting Python 2 Code to Python 3
...
@@ -21,21 +21,21 @@ Porting Python 2 Code to Python 3
Choosing a Strategy
Choosing a Strategy
===================
===================
When a project
makes the decision that it's time
to support both Python 2 & 3,
When a project
chooses
to support both Python 2 & 3,
a decision needs to be made as to how to go about accomplishing that goal.
a decision needs to be made as to how to go about accomplishing that goal.
The chosen strategy will depend on how large the project's existing
The chosen strategy will depend on how large the project's existing
codebase is and how much divergence you want from your Python 2 codebase from
codebase is and how much divergence you want from your current Python 2 codebase
your Python 3 one (e.g., starting a new version with Python 3).
(e.g., changing your code to work simultaneously with Python 2 and 3).
If your project is brand-new or does not have a large codebase, then you may
want to consider writing/porting :ref:`all of your code for Python 3
and use 3to2 <use_3to2>` to port your code for Python 2.
If you would prefer to maintain a codebase which is semantically **and**
If you would prefer to maintain a codebase which is semantically **and**
syntactically compatible with Python 2 & 3 simultaneously, you can write
syntactically compatible with Python 2 & 3 simultaneously, you can write
:ref:`use_same_source`. While this tends to lead to somewhat non-idiomatic
:ref:`use_same_source`. While this tends to lead to somewhat non-idiomatic
code, it does mean you keep a rapid development process for you, the developer.
code, it does mean you keep a rapid development process for you, the developer.
If your project is brand-new or does not have a large codebase, then you may
want to consider writing/porting :ref:`all of your code for Python 3
and use 3to2 <use_3to2>` to port your code for Python 2.
Finally, you do have the option of :ref:`using 2to3 <use_2to3>` to translate
Finally, you do have the option of :ref:`using 2to3 <use_2to3>` to translate
Python 2 code into Python 3 code (with some manual help). This can take the
Python 2 code into Python 3 code (with some manual help). This can take the
form of branching your code and using 2to3 to start a Python 3 branch. You can
form of branching your code and using 2to3 to start a Python 3 branch. You can
...
@@ -55,10 +55,10 @@ Regardless of what strategy you pick, there are a few things you should
...
@@ -55,10 +55,10 @@ Regardless of what strategy you pick, there are a few things you should
consider.
consider.
One is make sure you have a robust test suite. You need to make sure everything
One is make sure you have a robust test suite. You need to make sure everything
continues to work, just like when you support a new minor
version of Python.
continues to work, just like when you support a new minor
/feature release of
This means making sure your test suite is thorough and is ported properly
Python. This means making sure your test suite is thorough and is ported
between Python 2 & 3. You will also most likely want to use something like tox_
properly between Python 2 & 3. You will also most likely want to use something
to automate testing between both a Python 2 and Python 3 VM
.
like tox_ to automate testing between both a Python 2 and Python 3 interpreter
.
Two, once your project has Python 3 support, make sure to add the proper
Two, once your project has Python 3 support, make sure to add the proper
classifier on the Cheeseshop_ (PyPI_). To have your project listed as Python 3
classifier on the Cheeseshop_ (PyPI_). To have your project listed as Python 3
...
@@ -98,7 +98,8 @@ guard.
...
@@ -98,7 +98,8 @@ guard.
Four, read all the approaches. Just because some bit of advice applies to one
Four, read all the approaches. Just because some bit of advice applies to one
approach more than another doesn't mean that some advice doesn't apply to other
approach more than another doesn't mean that some advice doesn't apply to other
strategies.
strategies. This is especially true of whether you decide to use 2to3 or be
source-compatible; tips for one approach almost always apply to the other.
Five, drop support for older Python versions if possible. `Python 2.5`_
Five, drop support for older Python versions if possible. `Python 2.5`_
introduced a lot of useful syntax and libraries which have become idiomatic
introduced a lot of useful syntax and libraries which have become idiomatic
...
@@ -108,6 +109,14 @@ compatibility much easier if you are going from Python 2 to 3.
...
@@ -108,6 +109,14 @@ compatibility much easier if you are going from Python 2 to 3.
of Python which you believe can be your minimum support version
of Python which you believe can be your minimum support version
and work from there.
and work from there.
Six, target the newest version of Python 3 that you can. Beyond just the usual
bugfixes, compatibility has continued to improve between Python 2 and 3 as time
has passed. This is especially true for Python 3.3 where the ``u`` prefix for
strings is allowed, making source-compatible Python code easier.
Seven, make sure to look at the `Other Resources`_ for tips from other people
which may help you out.
.. _tox: http://codespeak.net/tox/
.. _tox: http://codespeak.net/tox/
.. _Cheeseshop:
.. _Cheeseshop:
...
@@ -169,8 +178,8 @@ experimental translation just to see how long it takes to evaluate whether you
...
@@ -169,8 +178,8 @@ experimental translation just to see how long it takes to evaluate whether you
prefer this approach compared to using :ref:`use_same_source` or simply keeping
prefer this approach compared to using :ref:`use_same_source` or simply keeping
a separate Python 3 codebase.
a separate Python 3 codebase.
Below are the typical steps taken by a project which
uses a 2to3-based approach
Below are the typical steps taken by a project which
tries to support
to supporting Python 2 & 3
.
Python 2 & 3 while keeping the code directly executable by Python 2
.
Support Python 2.7
Support Python 2.7
...
@@ -215,7 +224,9 @@ string with a ``u`` prefix to get the same effect. But regardless of whether
...
@@ -215,7 +224,9 @@ string with a ``u`` prefix to get the same effect. But regardless of whether
you use this future statement or not, you **must** make sure you know exactly
you use this future statement or not, you **must** make sure you know exactly
which Python 2 strings you want to be bytes, and which are to be strings. This
which Python 2 strings you want to be bytes, and which are to be strings. This
means you should, **at minimum** mark all strings that are meant to be text
means you should, **at minimum** mark all strings that are meant to be text
strings with a ``u`` prefix if you do not use this future statement.
strings with a ``u`` prefix if you do not use this future statement. Python 3.3
allows strings to continue to have the ``u`` prefix (it's a no-op in that case)
to make it easier for code to be source-compatible between Python 2 & 3.
Bytes literals
Bytes literals
...
@@ -226,6 +237,15 @@ are meant to contain bytes with a ``b`` prefix help to very clearly delineate
...
@@ -226,6 +237,15 @@ are meant to contain bytes with a ``b`` prefix help to very clearly delineate
what is and is not a Python 3 string. When you run 2to3 on code, all Python 2
what is and is not a Python 3 string. When you run 2to3 on code, all Python 2
strings become Python 3 strings **unless** they are prefixed with ``b``.
strings become Python 3 strings **unless** they are prefixed with ``b``.
This point cannot be stressed enough: make sure you know what all of your string
literals in Python 2 are meant to become in Python 3. Any string literal that
should be treated as bytes should have the ``b`` prefix. Any string literal
that should be Unicode/text in Python 2 should either have the ``u`` literal
(supported, but ignored, in Python 3.3 and later) or you should have
``from __future__ import unicode_literals`` at the top of the file. But the key
point is you should know how Python 3 will treat everyone one of your string
literals and you should mark them as appropriate.
There are some differences between byte literals in Python 2 and those in
There are some differences between byte literals in Python 2 and those in
Python 3 thanks to the bytes type just being an alias to ``str`` in Python 2.
Python 3 thanks to the bytes type just being an alias to ``str`` in Python 2.
Probably the biggest "gotcha" is that indexing results in different values. In
Probably the biggest "gotcha" is that indexing results in different values. In
...
@@ -264,6 +284,16 @@ other words, unless you are only supporting Python 2.7 or a version earlier
...
@@ -264,6 +284,16 @@ other words, unless you are only supporting Python 2.7 or a version earlier
than Python 2.5, use the __future__ statement.
than Python 2.5, use the __future__ statement.
Mark all Unicode strings with a ``u`` prefix
'''''''''''''''''''''''''''''''''''''''''''''
While Python 2.6 has a ``__future__`` statement to automatically cause Python 2
to treat all string literals as Unicode, Python 2.5 does not have that shortcut.
This means you should go through and mark all string literals with a ``u``
prefix to turn them explicitly into Unicode strings where appropriate. That
leaves all unmarked string literals to be considered byte literals in Python 3.
Handle Common "Gotchas"
Handle Common "Gotchas"
-----------------------
-----------------------
...
@@ -708,6 +738,7 @@ thus helping provide information for this document):
...
@@ -708,6 +738,7 @@ thus helping provide information for this document):
* http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/
* http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/
* http://lucumr.pocoo.org/2010/2/11/porting-to-python-3-a-guide/
* http://lucumr.pocoo.org/2010/2/11/porting-to-python-3-a-guide/
* http://wiki.python.org/moin/PortingPythonToPy3k
* http://wiki.python.org/moin/PortingPythonToPy3k
* https://wiki.ubuntu.com/Python/3
If you feel there is something missing from this document that should be added,
If you feel there is something missing from this document that should be added,
please email the python-porting_ mailing list.
please email the python-porting_ mailing list.
...
...
Misc/NEWS
View file @
b7e6b895
...
@@ -1110,6 +1110,8 @@ Tools/Demos
...
@@ -1110,6 +1110,8 @@ Tools/Demos
Documentation
Documentation
-------------
-------------
-
Touched
up
the
Python
2
to
3
porting
guide
.
-
Issue
#
14674
:
Add
a
discussion
of
the
`
json
`
module
's standard compliance.
-
Issue
#
14674
:
Add
a
discussion
of
the
`
json
`
module
's standard compliance.
Patch by Chris Rebert.
Patch by Chris Rebert.
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment