Django 1.5 is the first version of Django to support Python 3. The same code\nruns both on Python 2 (≥ 2.6.5) and Python 3 (≥ 3.2), thanks to the six\ncompatibility layer.
\nThis document is primarily targeted at authors of pluggable applications\nwho want to support both Python 2 and 3. It also describes guidelines that\napply to Django's code.
\nThis document assumes that you are familiar with the changes between Python 2\nand Python 3. If you aren't, read Python's official porting guide first. Refreshing your knowledge of unicode handling on\nPython 2 and 3 will help; the Pragmatic Unicode presentation is a good\nresource.
\nDjango uses the Python 2/3 Compatible Source strategy. Of course, you're\nfree to chose another strategy for your own code, especially if you don't need\nto stay compatible with Python 2. But authors of pluggable applications are\nencouraged to use the same porting strategy as Django itself.
\nWriting compatible code is much easier if you target Python ≥ 2.6. Django 1.5\nintroduces compatibility tools such as django.utils.six, which is a\ncustomized version of the six module. For convenience,\nforwards-compatible aliases were introduced in Django 1.4.2. If your\napplication takes advantage of these tools, it will require Django ≥ 1.4.2.
Obviously, writing compatible source code adds some overhead, and that can\ncause frustration. Django's developers have found that attempting to write\nPython 3 code that's compatible with Python 2 is much more rewarding than the\nopposite. Not only does that make your code more future-proof, but Python 3's\nadvantages (like the saner string handling) start shining quickly. Dealing\nwith Python 2 becomes a backwards compatibility requirement, and we as\ndevelopers are used to dealing with such constraints.
\nPorting tools provided by Django are inspired by this philosophy, and it's\nreflected throughout this guide.
\nThis step consists in:
\nAdding from __future__ import unicode_literals at the top of your Python\nmodules -- it's best to put it in each and every module, otherwise you'll\nkeep 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.
\nHowever, Django applications generally don't need bytestrings, since Django\nonly exposes unicode interfaces to the programmer. Python 3 discourages using\nbytestrings, except for binary data or byte-oriented interfaces. Python 2\nmakes bytestrings and unicode strings effectively interchangeable, as long as\nthey only contain ASCII data. Take advantage of this to use unicode strings\nwherever possible and avoid the b prefixes.
Python 2's unicode type was renamed str in Python 3,\nstr() was renamed bytes, and basestring disappeared.\nsix provides tools to deal with these\nchanges.
Django also contains several string related classes and functions in the\ndjango.utils.encoding and django.utils.safestring modules. Their\nnames used the words str, which doesn't mean the same thing in Python 2\nand Python 3, and unicode, which doesn't exist in Python 3. In order to\navoid ambiguity and confusion these concepts were renamed bytes and\ntext.
Here are the name changes in django.utils.encoding:
Old name | \nNew name | \n
|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
For backwards compatibility, the old names still work on Python 2. Under\nPython 3, smart_str is an alias for smart_text.
For forwards compatibility, the new names work as of Django 1.4.2.
\n\ndjango.utils.safestring is mostly used via the\nmark_safe() and\nmark_for_escaping() functions, which didn't\nchange. In case you're using the internals, here are the name changes:
Old name | \nNew name | \n
|---|---|
| \n
| \n
| \n
| \n
| \n
| \n
| \n
| \n
For backwards compatibility, the old names still work on Python 2. Under\nPython 3, EscapeString and SafeString are aliases for EscapeText\nand SafeText respectively.
For forwards compatibility, the new names work as of Django 1.4.2.
\n__str__() and __unicode__() methodsLink to this heading#In Python 2, the object model specifies __str__() and\n` __unicode__()`_ methods. If these methods exist, they must return\nstr (bytes) and unicode (text) respectively.
The print statement and the str built-in call\n__str__() to determine the human-readable representation of an\nobject. The unicode built-in calls ` __unicode__()`_ if it\nexists, and otherwise falls back to __str__() and decodes the\nresult with the system encoding. Conversely, the\nModel base class automatically derives\n__str__() from ` __unicode__()`_ by encoding to UTF-8.
In Python 3, there's simply __str__(), which must return str\n(text).
(It is also possible to define __bytes__(), but Django applications\nhave little use for that method, because they hardly ever deal with bytes.)
Django provides a simple way to define __str__() and\n` __unicode__()`_ methods that work on Python 2 and 3: you must\ndefine a __str__() method returning text and to apply the\npython_2_unicode_compatible() decorator.
On Python 3, the decorator is a no-op. On Python 2, it defines appropriate\n` __unicode__()`_ and __str__() methods (replacing the\noriginal __str__() method in the process). Here's an example:
from __future__ import unicode_literals\nfrom django.utils.encoding import python_2_unicode_compatible\n\n@python_2_unicode_compatible\nclass MyClass(object):\n def __str__(self):\n return "Instance of my class"\nThis technique is the best match for Django's porting philosophy.
\nFor forwards compatibility, this decorator is available as of Django 1.4.2.
\nFinally, note that __repr__() must return a str on all\nversions of Python.
dict and dict-like classesLink to this heading#dict.keys(), dict.items() and dict.values() return lists in\nPython 2 and iterators in Python 3. QueryDict and the\ndict-like classes defined in django.utils.datastructures\nbehave likewise in Python 3.
six provides compatibility functions to work around this change:\niterkeys(), iteritems(), and itervalues().\nIt also contains an undocumented iterlists function that works well for\ndjango.utils.datastructures.MultiValueDict and its subclasses.
HttpRequest and HttpResponse objectsLink to this heading#According to PEP 3333:
\nheaders are always str objects,
input and output streams are always bytes objects.
Specifically, HttpResponse.content\ncontains bytes, which may become an issue if you compare it with a\nstr in your tests. The preferred solution is to rely on\nassertContains() and\nassertNotContains(). These methods accept a\nresponse and a unicode string as arguments.
The following guidelines are enforced in Django's source code. They're also\nrecommended for third-party applications that follow the same porting strategy.
\nIn Python 3, all strings are considered Unicode by default. The unicode\ntype from Python 2 is called str in Python 3, and str becomes\nbytes.
You mustn't use the u prefix before a unicode string literal because it's\na syntax error in Python 3.2. You must prefix byte strings with b.
In order to enable the same behavior in Python 2, every module must import\nunicode_literals from __future__:
from __future__ import unicode_literals\n\nmy_string = "This is an unicode literal"\nmy_bytestring = b"This is a bytestring"\nIf you need a byte string literal under Python 2 and a unicode string literal\nunder Python 3, use the str builtin:
str('my string')\nIn Python 3, there aren't any automatic conversions between str and\nbytes, and the codecs module became more strict. str.encode()\nalways returns bytes, and bytes.decode always returns str. As a\nconsequence, the following pattern is sometimes necessary:
value = value.encode('ascii', 'ignore').decode('ascii')\nBe cautious if you have to index bytestrings.
\nWhen you capture exceptions, use the as keyword:
try:\n ...\nexcept MyException as exc:\n ...\nThis older syntax was removed in Python 3:
\ntry:\n ...\nexcept MyException, exc: # Don't do that!\n ...\nThe syntax to reraise an exception with a different traceback also changed.\nUse six.reraise().
Use the patterns below to handle magic methods renamed in Python 3.
\nclass MyIterator(six.Iterator):\n def __iter__(self):\n return self # implement some logic here\n\n def __next__(self):\n raise StopIteration # implement some logic here\nclass MyBoolean(object):\n\n def __bool__(self):\n return True # implement some logic here\n\n def __nonzero__(self): # Python 2 compatibility\n return type(self).__bool__(self)\nclass MyDivisible(object):\n\n def __truediv__(self, other):\n return self / other # implement some logic here\n\n def __div__(self, other): # Python 2 compatibility\n return type(self).__truediv__(self, other)\n\n def __itruediv__(self, other):\n return self // other # implement some logic here\n\n def __idiv__(self, other): # Python 2 compatibility\n return type(self).__itruediv__(self, other)\nSpecial methods are looked up on the class and not on the instance to reflect\nthe behavior of the Python interpreter.
\nsix is the canonical compatibility library for supporting Python 2 and 3 in\na single codebase. Read its documentation!
\nA customized version of six is bundled with Django\nas of version 1.4.2. You can import it as django.utils.six.
Here are the most common changes required to write compatible code.
\nThe basestring and unicode types were removed in Python 3, and the\nmeaning of str changed. To test these types, use the following idioms:
isinstance(myvalue, six.string_types) # replacement for basestring\nisinstance(myvalue, six.text_type) # replacement for unicode\nisinstance(myvalue, bytes) # replacement for str\nPython ≥ 2.6 provides bytes as an alias for str, so you don't need\nsix.binary_type.
longLink to this heading#The long type no longer exists in Python 3. 1L is a syntax error. Use\nsix.integer_types check if a value is an integer or a long:
isinstance(myvalue, six.integer_types) # replacement for (int, long)\nxrangeLink to this heading#If you use xrange on Python 2, import six.moves.range and use that\ninstead. You can also import six.moves.xrange (it's equivalent to\nsix.moves.range) but the first technique allows you to simply drop the\nimport when dropping support for Python 2.
Some modules were renamed in Python 3. The django.utils.six.moves\nmodule (based on the six.moves module) provides a\ncompatible location to import them.
PY2Link to this heading#If you need different code in Python 2 and Python 3, check six.PY2:
if six.PY2:\n # compatibility code for Python 2\nThis is a last resort solution when six doesn't provide an appropriate\nfunction.
sixLink to this heading#The version of six bundled with Django (django.utils.six) includes a few\ncustomizations for internal use only.