Porting to Python 3¶

Unicode literals¶

This step consists in:

• Adding from __future__ import unicode_literals at the top of your Python modules – it’s best to put it in each and every module, otherwise you’ll keep checking the top of your files to see which mode is in effect;
• Removing the u prefix before unicode strings;
• Adding a b prefix before bytestrings.

Performing these changes systematically guarantees backwards compatibility.

However, Django applications generally don’t need bytestrings, since Django only exposes unicode interfaces to the programmer. Python 3 discourages using bytestrings, except for binary data or byte-oriented interfaces. Python 2 makes bytestrings and unicode strings effectively interchangeable, as long as they only contain ASCII data. Take advantage of this to use unicode strings wherever possible and avoid the b prefixes.

String handling¶

Python 2’s unicode() type was renamed str() in Python 3, str() was renamed bytes(), and basestring() disappeared. six provides tools to deal with these changes.

Django also contains several string related classes and functions in the django.utils.encoding and django.utils.safestring modules. Their names used the words str, which doesn’t mean the same thing in Python 2 and Python 3, and unicode, which doesn’t exist in Python 3. In order to avoid ambiguity and confusion these concepts were renamed bytes and text.

Here are the name changes in django.utils.encoding:

For backwards compatibility, the old names still work on Python 2. Under Python 3, smart_str is an alias for smart_text.

For forwards compatibility, the new names work as of Django 1.4.2.

django.utils.safestring is mostly used via the mark_safe() and mark_for_escaping() functions, which didn’t change. In case you’re using the internals, here are the name changes:

For backwards compatibility, the old names still work on Python 2. Under Python 3, EscapeString and SafeString are aliases for EscapeText and SafeText respectively.

For forwards compatibility, the new names work as of Django 1.4.2.

__str__() and __unicode__() methods¶

In Python 2, the object model specifies __str__() and __unicode__() methods. If these methods exist, they must return str (bytes) and unicode (text) respectively.

The print statement and the str() built-in call __str__() to determine the human-readable representation of an object. The unicode() built-in calls __unicode__() if it exists, and otherwise falls back to __str__() and decodes the result with the system encoding. Conversely, the Model base class automatically derives __str__() from __unicode__() by encoding to UTF-8.

In Python 3, there’s simply __str__(), which must return str (text).

(It is also possible to define __bytes__(), but Django application have little use for that method, because they hardly ever deal with bytes.)

Django provides a simple way to define __str__() and __unicode__() methods that work on Python 2 and 3: you must define a __str__() method returning text and to apply the python_2_unicode_compatible() decorator.

On Python 3, the decorator is a no-op. On Python 2, it defines appropriate __unicode__() and __str__() methods (replacing the original __str__() method in the process). Here’s an example:

from __future__ import unicode_literals
from django.utils.encoding import python_2_unicode_compatible

@python_2_unicode_compatible
class MyClass(object):
    def __str__(self):
        return "Instance of my class"

This technique is the best match for Django’s porting philosophy.

For forwards compatibility, this decorator is available as of Django 1.4.2.

Finally, note that __repr__() must return a str on all versions of Python.

dict and dict-like classes¶

dict.keys(), dict.items() and dict.values() return lists in Python 2 and iterators in Python 3. QueryDict and the dict-like classes defined in django.utils.datastructures behave likewise in Python 3.

six provides compatibility functions to work around this change: iterkeys(), iteritems(), and itervalues(). Django’s bundled version adds iterlists() for django.utils.datastructures.MultiValueDict and its subclasses.

HttpRequest and HttpResponse objects¶

According to PEP 3333:

• headers are always str objects,
• input and output streams are always bytes objects.

Specifically, HttpResponse.content contains bytes, which may become an issue if you compare it with a str in your tests. The preferred solution is to rely on assertContains() and assertNotContains(). These methods accept a response and a unicode string as arguments.

Syntax requirements¶

from __future__ import unicode_literals

my_string = "This is an unicode literal"
my_bytestring = b"This is a bytestring"

str('my string')

value = value.encode('ascii', 'ignore').decode('ascii')

try:
    ...
except MyException as exc:
    ...

try:
    ...
except MyException, exc:    # Don't do that!
    ...

Magic methods¶

Use the patterns below to handle magic methods renamed in Python 3.

class MyIterator(six.Iterator):
    def __iter__(self):
        return self             # implement some logic here

    def __next__(self):
        raise StopIteration     # implement some logic here

class MyBoolean(object):

    def __bool__(self):
        return True             # implement some logic here

    def __nonzero__(self):      # Python 2 compatibility
        return type(self).__bool__(self)

class MyDivisible(object):

    def __truediv__(self, other):
        return self / other     # implement some logic here

    def __div__(self, other):   # Python 2 compatibility
        return type(self).__truediv__(self, other)

    def __itruediv__(self, other):
        return self // other    # implement some logic here

    def __idiv__(self, other):  # Python 2 compatibility
        return type(self).__itruediv__(self, other)

Writing compatible code with six¶

six is the canonical compatibility library for supporting Python 2 and 3 in a single codebase. Read its documentation!

six is bundled with Django as of version 1.4.2. You can import it as django.utils.six.

Here are the most common changes required to write compatible code.

isinstance(myvalue, six.string_types)       # replacement for basestring
isinstance(myvalue, six.text_type)          # replacement for unicode
isinstance(myvalue, bytes)                  # replacement for str

isinstance(myvalue, six.integer_types)      # replacement for (int, long)

try:
    from urllib.parse import urlparse, urlunparse
except ImportError:     # Python 2
    from urlparse import urlparse, urlunparse

if six.PY3:
    # do stuff Python 3-wise
else:
    # do stuff Python 2-wise

Customizations of six¶

The version of six bundled with Django includes one extra function:

iterlists(MultiValueDict)¶

Returns an iterator over the lists of values of a MultiValueDict. This replaces iterlists() on Python 2 and lists() on Python 3.

assertRaisesRegex(testcase, *args, **kwargs)¶

This replaces testcase.assertRaisesRegexp on Python 2, and testcase.assertRaisesRegex on Python 3. assertRaisesRegexp still exists in current Python3 versions, but issues a warning.

In addition to six’ defaults moves, Django’s version provides thread as _thread and dummy_thread as _dummy_thread.