Strings and Unicode

As of Python 2.6 the 2.x line includes a "bytes = str" alias in the builtins. Along with the bytes literal syntax, this allows binary data stored in a str instance to be clearly flagged so that it will use the correct type when the code is run in 3.x (either directly or via the 2to3 conversion tool). The reason it is done this way rather than backporting the 3.x bytes type is that most 2.x APIs that expect immutable binary data expect it as an 8-bit str instance.

future solves this problem by providing backports of the bytes and str objects from Python 3 that inherit from Python 2's str and unicode objects, respectively.

To support versions earlier than 2.6, it is possible to define the alias at the top of the module:

try:
  bytes # Forward compatibility with Py3k
except NameError:
  bytes = str

When using "from __future__ import unicode_literals" in a module, it may also be useful to insert "str = unicode" near the top of the module. This will ensure that "isinstance('', str)" remains true in that module:

try:
  str = unicode
except NameError:
  pass # Forward compatibility with Py3k

Supporting older Python versions

from __future__ import print_function
print('hello world')

print 'hello world'

import sys
sys.stdout.write('hello world\n')

try:
    1 / 0
except ZeroDivisionError as e:
    pass

import sys
try:
    open('/path/to/some/file')
except IOError:
    _, e, _ = sys.exc_info()

Relative Imports

Python 3 makes a distinction between relative and absolute imports, dropping support for implicit relative imports. In Python 2.5+, use from __future__ import absolute_import to get the same behavior as Python 3. To support older versions as well, only use absolute imports. Replace a relative import:

from xyz import abc

with an absolute import:

from mypackage.xyz import abc

Integer Division

Make sure to use from __future__ import division (introduced in Python 2.2) to get the non-truncating behavior, which is default in Python 3.

Strings and Bytes

Design decisions needs to be taken what exactly must be represented as bytes, and what as strings (Unicode data). In many cases, this is easy. However, data sent or received over pipes or sockets are usually in binary mode, so explicit conversions may be necessary. For example, the Postgres API requires SQL queries to be transmitted in the connection encoding. It is probably easiest to convert the queries to the connection encoding as early as possible.

The standard IO streams (sys.stdin, sys.stdout, sys.stderr), are in text mode by default in Python 3. Calling sys.stdout.write(some_binary_data) will fail. To write binary data to standard out, you must do the following:

sys.stdout.flush()
sys.stdout.buffer.write(some_binary_data)

The flush() clears out any text (unicode) data that is stored in the TextIOWrapper, and the buffer attribute provides access to the lower-level binary stream. If you are only writing binary data, you can remove the text layer with sys.stdout = sys.stdout.detach() in Python 3.1; in Python 3.0, do sys.stdout = sys.stdout.buffer.

Martin's notes from psycopg2

• the buffer object is gone; I use memoryview in 3.x.
• various tests where in the code of the form if version_major == and version_minor > 4 (say, or 5) This will break for 3.x; you have to write if (version_major == 2 and version_minor > 4) or version_major > 2
• Python code 2: setup.py needs to run in both versions. I had to replace popen2 with subprocess if available. Also, map() now returns an iterator, which I explicitly convert into list, and so on.
• Python code 3: the test suite doesn't get installed, and hence not auto-converted with 2to3 support. I explicitly added a 2to3 conversion into the test runner, which copies the py3 version of the test into a separate directory.

Differences in specific libraries

These are porting notes on differences in third party libraries when run on Python 2 and Python 3.

• PyQt4

More links

• a bunch of very useful reference code: http://code.google.com/p/python-incompatibility/
• PortingDjangoTo3k
• Porting Durus / QP / Qpy / Dulcinea, using approach targeting Python 2 and Python 3 off same code base - packages released but not in pypi yet.
• Early2to3Migrations
• Stephan Deibel's blog post on code usable from Python 2.0 through 3.0
• Python code that demonstrates differences between 2.5 and 3.0, and ways of making the same code run on 2.6 and 3.x
• Georg Brandl's blog post collecting some information: http://pythonic.pocoo.org/2008/12/14/python-3-porting-resources
• A blog post about porting experience: psycopg2 porting to Python 3: a report
• Reference Card: Moving from Python 2 to Python 3: http://ptgmedia.pearsoncmg.com/imprint_downloads/informit/promotions/python/python2python3.pdf
• Lennart Regebro's overview of Porting strategies
• Dropbox' migration to Python 3
• Instagram's migration to Python 3