<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Porting to Python 3 — Django 1.11.20 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Security in Django" href="security.html" />
<link rel="prev" title="Pagination" href="pagination.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head><body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.11.20 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="pagination.html" title="Pagination">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="security.html" title="Security in Django">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="topics-python3">
<div class="section" id="s-porting-to-python-3">
<span id="porting-to-python-3"></span><h1>Porting to Python 3<a class="headerlink" href="#porting-to-python-3" title="Permalink to this headline">¶</a></h1>
<p>Django 1.5 is the first version of Django to support Python 3. The same code
runs both on Python 2 (≥ 2.6.5) and Python 3 (≥ 3.2), thanks to the <a class="reference external" href="https://pythonhosted.org/six/">six</a>
compatibility layer.</p>
<p>This document is primarily targeted at authors of pluggable applications
who want to support both Python 2 and 3. It also describes guidelines that
apply to Django’s code.</p>
<div class="section" id="s-philosophy">
<span id="philosophy"></span><h2>Philosophy<a class="headerlink" href="#philosophy" title="Permalink to this headline">¶</a></h2>
<p>This document assumes that you are familiar with the changes between Python 2
and Python 3. If you aren’t, read <span class="xref std std-ref">Python’s official porting guide</span> first. Refreshing your knowledge of unicode handling on
Python 2 and 3 will help; the <a class="reference external" href="http://nedbatchelder.com/text/unipain.html">Pragmatic Unicode</a> presentation is a good
resource.</p>
<p>Django uses the <em>Python 2/3 Compatible Source</em> strategy. Of course, you’re
free to chose another strategy for your own code, especially if you don’t need
to stay compatible with Python 2. But authors of pluggable applications are
encouraged to use the same porting strategy as Django itself.</p>
<p>Writing compatible code is much easier if you target Python ≥ 2.6. Django 1.5
introduces compatibility tools such as <a class="reference internal" href="#module-django.utils.six" title="django.utils.six"><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.utils.six</span></code></a>, which is a
customized version of the <code class="xref py py-mod docutils literal notranslate"><span class="pre">six</span> <span class="pre">module</span></code>. For convenience,
forwards-compatible aliases were introduced in Django 1.4.2. If your
application takes advantage of these tools, it will require Django ≥ 1.4.2.</p>
<p>Obviously, writing compatible source code adds some overhead, and that can
cause frustration. Django’s developers have found that attempting to write
Python 3 code that’s compatible with Python 2 is much more rewarding than the
opposite. Not only does that make your code more future-proof, but Python 3’s
advantages (like the saner string handling) start shining quickly. Dealing
with Python 2 becomes a backwards compatibility requirement, and we as
developers are used to dealing with such constraints.</p>
<p>Porting tools provided by Django are inspired by this philosophy, and it’s
reflected throughout this guide.</p>
</div>
<div class="section" id="s-porting-tips">
<span id="porting-tips"></span><h2>Porting tips<a class="headerlink" href="#porting-tips" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-unicode-literals">
<span id="unicode-literals"></span><h3>Unicode literals<a class="headerlink" href="#unicode-literals" title="Permalink to this headline">¶</a></h3>
<p>This step consists in:</p>
<ul class="simple">
<li>Adding <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span> <span class="pre">unicode_literals</span></code> 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;</li>
<li>Removing the <code class="docutils literal notranslate"><span class="pre">u</span></code> prefix before unicode strings;</li>
<li>Adding a <code class="docutils literal notranslate"><span class="pre">b</span></code> prefix before bytestrings.</li>
</ul>
<p>Performing these changes systematically guarantees backwards compatibility.</p>
<p>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 <code class="docutils literal notranslate"><span class="pre">b</span></code> prefixes.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Python 2’s <code class="docutils literal notranslate"><span class="pre">u</span></code> prefix is a syntax error in Python 3.2 but it will be
allowed again in Python 3.3 thanks to <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0414"><strong>PEP 414</strong></a>. Thus, this
transformation is optional if you target Python ≥ 3.3. It’s still
recommended, per the “write Python 3 code” philosophy.</p>
</div>
</div>
<div class="section" id="s-string-handling">
<span id="string-handling"></span><h3>String handling<a class="headerlink" href="#string-handling" title="Permalink to this headline">¶</a></h3>
<p>Python 2’s <a class="reference external" href="https://docs.python.org/2/library/functions.html#unicode">unicode</a> type was renamed <code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code> in Python 3,
<code class="docutils literal notranslate"><span class="pre">str()</span></code> was renamed <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code>, and <a class="reference external" href="https://docs.python.org/2/library/functions.html#basestring">basestring</a> disappeared.
<a class="reference external" href="https://pythonhosted.org/six/">six</a> provides <a class="reference internal" href="#string-handling-with-six"><span class="std std-ref">tools</span></a> to deal with these
changes.</p>
<p>Django also contains several string related classes and functions in the
<a class="reference internal" href="../ref/utils.html#module-django.utils.encoding" title="django.utils.encoding: A series of helper functions to manage character encoding."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.utils.encoding</span></code></a> and <a class="reference internal" href="../ref/utils.html#module-django.utils.safestring" title="django.utils.safestring: Functions and classes for working with strings that can be displayed safely without further escaping in HTML."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.utils.safestring</span></code></a> modules. Their
names used the words <code class="docutils literal notranslate"><span class="pre">str</span></code>, which doesn’t mean the same thing in Python 2
and Python 3, and <code class="docutils literal notranslate"><span class="pre">unicode</span></code>, which doesn’t exist in Python 3. In order to
avoid ambiguity and confusion these concepts were renamed <code class="docutils literal notranslate"><span class="pre">bytes</span></code> and
<code class="docutils literal notranslate"><span class="pre">text</span></code>.</p>
<p>Here are the name changes in <a class="reference internal" href="../ref/utils.html#module-django.utils.encoding" title="django.utils.encoding: A series of helper functions to manage character encoding."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.utils.encoding</span></code></a>:</p>
<table class="docutils">
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Old name</th>
<th class="head">New name</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">smart_str</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">smart_bytes</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">smart_unicode</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">smart_text</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">force_unicode</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">force_text</span></code></td>
</tr>
</tbody>
</table>
<p>For backwards compatibility, the old names still work on Python 2. Under
Python 3, <code class="docutils literal notranslate"><span class="pre">smart_str</span></code> is an alias for <code class="docutils literal notranslate"><span class="pre">smart_text</span></code>.</p>
<p>For forwards compatibility, the new names work as of Django 1.4.2.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="../ref/utils.html#module-django.utils.encoding" title="django.utils.encoding: A series of helper functions to manage character encoding."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.utils.encoding</span></code></a> was deeply refactored in Django 1.5 to
provide a more consistent API. Check its documentation for more
information.</p>
</div>
<p><a class="reference internal" href="../ref/utils.html#module-django.utils.safestring" title="django.utils.safestring: Functions and classes for working with strings that can be displayed safely without further escaping in HTML."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.utils.safestring</span></code></a> is mostly used via the
<a class="reference internal" href="../ref/utils.html#django.utils.safestring.mark_safe" title="django.utils.safestring.mark_safe"><code class="xref py py-func docutils literal notranslate"><span class="pre">mark_safe()</span></code></a> and
<a class="reference internal" href="../ref/utils.html#django.utils.safestring.mark_for_escaping" title="django.utils.safestring.mark_for_escaping"><code class="xref py py-func docutils literal notranslate"><span class="pre">mark_for_escaping()</span></code></a> functions, which didn’t
change. In case you’re using the internals, here are the name changes:</p>
<table class="docutils">
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Old name</th>
<th class="head">New name</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">EscapeString</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">EscapeBytes</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">EscapeUnicode</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">EscapeText</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">SafeString</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">SafeBytes</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">SafeUnicode</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">SafeText</span></code></td>
</tr>
</tbody>
</table>
<p>For backwards compatibility, the old names still work on Python 2. Under
Python 3, <code class="docutils literal notranslate"><span class="pre">EscapeString</span></code> and <code class="docutils literal notranslate"><span class="pre">SafeString</span></code> are aliases for <code class="docutils literal notranslate"><span class="pre">EscapeText</span></code>
and <code class="docutils literal notranslate"><span class="pre">SafeText</span></code> respectively.</p>
<p>For forwards compatibility, the new names work as of Django 1.4.2.</p>
</div>
<div class="section" id="s-str-and-unicode-methods">
<span id="str-and-unicode-methods"></span><h3><code class="docutils literal notranslate"><span class="pre">__str__()</span></code> and <code class="docutils literal notranslate"><span class="pre">__unicode__()</span></code> methods<a class="headerlink" href="#str-and-unicode-methods" title="Permalink to this headline">¶</a></h3>
<p>In Python 2, the object model specifies <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> and
` __unicode__()`_ methods. If these methods exist, they must return
<code class="docutils literal notranslate"><span class="pre">str</span></code> (bytes) and <code class="docutils literal notranslate"><span class="pre">unicode</span></code> (text) respectively.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">print</span></code> statement and the <code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code> built-in call
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> to determine the human-readable representation of an
object. The <code class="docutils literal notranslate"><span class="pre">unicode</span></code> built-in calls ` __unicode__()`_ if it
exists, and otherwise falls back to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> and decodes the
result with the system encoding. Conversely, the
<a class="reference internal" href="../ref/models/instances.html#django.db.models.Model" title="django.db.models.Model"><code class="xref py py-class docutils literal notranslate"><span class="pre">Model</span></code></a> base class automatically derives
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> from ` __unicode__()`_ by encoding to UTF-8.</p>
<p>In Python 3, there’s simply <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code>, which must return <code class="docutils literal notranslate"><span class="pre">str</span></code>
(text).</p>
<p>(It is also possible to define <code class="xref py py-meth docutils literal notranslate"><span class="pre">__bytes__()</span></code>, but Django applications
have little use for that method, because they hardly ever deal with <code class="docutils literal notranslate"><span class="pre">bytes</span></code>.)</p>
<p>Django provides a simple way to define <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> and
` __unicode__()`_ methods that work on Python 2 and 3: you must
define a <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> method returning text and to apply the
<a class="reference internal" href="../ref/utils.html#django.utils.encoding.python_2_unicode_compatible" title="django.utils.encoding.python_2_unicode_compatible"><code class="xref py py-func docutils literal notranslate"><span class="pre">python_2_unicode_compatible()</span></code></a> decorator.</p>
<p>On Python 3, the decorator is a no-op. On Python 2, it defines appropriate
` __unicode__()`_ and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> methods (replacing the
original <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> method in the process). Here’s an example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">unicode_literals</span>
<span class="kn">from</span> <span class="nn">django.utils.encoding</span> <span class="k">import</span> <span class="n">python_2_unicode_compatible</span>
<span class="nd">@python_2_unicode_compatible</span>
<span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="s2">"Instance of my class"</span>
</pre></div>
</div>
<p>This technique is the best match for Django’s porting philosophy.</p>
<p>For forwards compatibility, this decorator is available as of Django 1.4.2.</p>
<p>Finally, note that <code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code> must return a <code class="docutils literal notranslate"><span class="pre">str</span></code> on all
versions of Python.</p>
</div>
<div class="section" id="s-dict-and-dict-like-classes">
<span id="dict-and-dict-like-classes"></span><h3><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code> and <code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>-like classes<a class="headerlink" href="#dict-and-dict-like-classes" title="Permalink to this headline">¶</a></h3>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.keys()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.items()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.values()</span></code> return lists in
Python 2 and iterators in Python 3. <a class="reference internal" href="../ref/request-response.html#django.http.QueryDict" title="django.http.QueryDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueryDict</span></code></a> and the
<code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>-like classes defined in <code class="docutils literal notranslate"><span class="pre">django.utils.datastructures</span></code>
behave likewise in Python 3.</p>
<p><a class="reference external" href="https://pythonhosted.org/six/">six</a> provides compatibility functions to work around this change:
<code class="xref py py-func docutils literal notranslate"><span class="pre">iterkeys()</span></code>, <code class="xref py py-func docutils literal notranslate"><span class="pre">iteritems()</span></code>, and <code class="xref py py-func docutils literal notranslate"><span class="pre">itervalues()</span></code>.
It also contains an undocumented <code class="docutils literal notranslate"><span class="pre">iterlists</span></code> function that works well for
<code class="docutils literal notranslate"><span class="pre">django.utils.datastructures.MultiValueDict</span></code> and its subclasses.</p>
</div>
<div class="section" id="s-httprequest-and-httpresponse-objects">
<span id="httprequest-and-httpresponse-objects"></span><h3><a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> and <a class="reference internal" href="../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpResponse</span></code></a> objects<a class="headerlink" href="#httprequest-and-httpresponse-objects" title="Permalink to this headline">¶</a></h3>
<p>According to <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-3333"><strong>PEP 3333</strong></a>:</p>
<ul class="simple">
<li>headers are always <code class="docutils literal notranslate"><span class="pre">str</span></code> objects,</li>
<li>input and output streams are always <code class="docutils literal notranslate"><span class="pre">bytes</span></code> objects.</li>
</ul>
<p>Specifically, <a class="reference internal" href="../ref/request-response.html#django.http.HttpResponse.content" title="django.http.HttpResponse.content"><code class="xref py py-attr docutils literal notranslate"><span class="pre">HttpResponse.content</span></code></a>
contains <code class="docutils literal notranslate"><span class="pre">bytes</span></code>, which may become an issue if you compare it with a
<code class="docutils literal notranslate"><span class="pre">str</span></code> in your tests. The preferred solution is to rely on
<a class="reference internal" href="testing/tools.html#django.test.SimpleTestCase.assertContains" title="django.test.SimpleTestCase.assertContains"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertContains()</span></code></a> and
<a class="reference internal" href="testing/tools.html#django.test.SimpleTestCase.assertNotContains" title="django.test.SimpleTestCase.assertNotContains"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertNotContains()</span></code></a>. These methods accept a
response and a unicode string as arguments.</p>
</div>
</div>
<div class="section" id="s-coding-guidelines">
<span id="coding-guidelines"></span><h2>Coding guidelines<a class="headerlink" href="#coding-guidelines" title="Permalink to this headline">¶</a></h2>
<p>The following guidelines are enforced in Django’s source code. They’re also
recommended for third-party applications that follow the same porting strategy.</p>
<div class="section" id="s-syntax-requirements">
<span id="syntax-requirements"></span><h3>Syntax requirements<a class="headerlink" href="#syntax-requirements" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-unicode">
<span id="unicode"></span><h4>Unicode<a class="headerlink" href="#unicode" title="Permalink to this headline">¶</a></h4>
<p>In Python 3, all strings are considered Unicode by default. The <code class="docutils literal notranslate"><span class="pre">unicode</span></code>
type from Python 2 is called <code class="docutils literal notranslate"><span class="pre">str</span></code> in Python 3, and <code class="docutils literal notranslate"><span class="pre">str</span></code> becomes
<code class="docutils literal notranslate"><span class="pre">bytes</span></code>.</p>
<p>You mustn’t use the <code class="docutils literal notranslate"><span class="pre">u</span></code> prefix before a unicode string literal because it’s
a syntax error in Python 3.2. You must prefix byte strings with <code class="docutils literal notranslate"><span class="pre">b</span></code>.</p>
<p>In order to enable the same behavior in Python 2, every module must import
<code class="docutils literal notranslate"><span class="pre">unicode_literals</span></code> from <code class="docutils literal notranslate"><span class="pre">__future__</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">unicode_literals</span>
<span class="n">my_string</span> <span class="o">=</span> <span class="s2">"This is an unicode literal"</span>
<span class="n">my_bytestring</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">"This is a bytestring"</span>
</pre></div>
</div>
<p>If you need a byte string literal under Python 2 and a unicode string literal
under Python 3, use the <code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code> builtin:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">str</span><span class="p">(</span><span class="s1">'my string'</span><span class="p">)</span>
</pre></div>
</div>
<p>In Python 3, there aren’t any automatic conversions between <code class="docutils literal notranslate"><span class="pre">str</span></code> and
<code class="docutils literal notranslate"><span class="pre">bytes</span></code>, and the <code class="xref py py-mod docutils literal notranslate"><span class="pre">codecs</span></code> module became more strict. <code class="xref py py-meth docutils literal notranslate"><span class="pre">str.encode()</span></code>
always returns <code class="docutils literal notranslate"><span class="pre">bytes</span></code>, and <code class="docutils literal notranslate"><span class="pre">bytes.decode</span></code> always returns <code class="docutils literal notranslate"><span class="pre">str</span></code>. As a
consequence, the following pattern is sometimes necessary:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">value</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s1">'ascii'</span><span class="p">,</span> <span class="s1">'ignore'</span><span class="p">)</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">'ascii'</span><span class="p">)</span>
</pre></div>
</div>
<p>Be cautious if you have to <a class="reference external" href="https://docs.python.org/3/howto/pyporting.html#text-versus-binary-data">index bytestrings</a>.</p>
</div>
<div class="section" id="s-exceptions">
<span id="exceptions"></span><h4>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h4>
<p>When you capture exceptions, use the <code class="docutils literal notranslate"><span class="pre">as</span></code> keyword:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
<span class="o">...</span>
<span class="k">except</span> <span class="n">MyException</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
<span class="o">...</span>
</pre></div>
</div>
<p>This older syntax was removed in Python 3:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
<span class="o">...</span>
<span class="k">except</span> <span class="n">MyException</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span> <span class="c1"># Don't do that!</span>
<span class="o">...</span>
</pre></div>
</div>
<p>The syntax to reraise an exception with a different traceback also changed.
Use <code class="xref py py-func docutils literal notranslate"><span class="pre">six.reraise()</span></code>.</p>
</div>
</div>
<div class="section" id="s-magic-methods">
<span id="magic-methods"></span><h3>Magic methods<a class="headerlink" href="#magic-methods" title="Permalink to this headline">¶</a></h3>
<p>Use the patterns below to handle magic methods renamed in Python 3.</p>
<div class="section" id="s-iterators">
<span id="iterators"></span><h4>Iterators<a class="headerlink" href="#iterators" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyIterator</span><span class="p">(</span><span class="n">six</span><span class="o">.</span><span class="n">Iterator</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span> <span class="c1"># implement some logic here</span>
<span class="k">def</span> <span class="nf">__next__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">raise</span> <span class="ne">StopIteration</span> <span class="c1"># implement some logic here</span>
</pre></div>
</div>
</div>
<div class="section" id="s-boolean-evaluation">
<span id="boolean-evaluation"></span><h4>Boolean evaluation<a class="headerlink" href="#boolean-evaluation" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyBoolean</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__bool__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="kc">True</span> <span class="c1"># implement some logic here</span>
<span class="k">def</span> <span class="nf">__nonzero__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="c1"># Python 2 compatibility</span>
<span class="k">return</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="fm">__bool__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-division">
<span id="division"></span><h4>Division<a class="headerlink" href="#division" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyDivisible</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__truediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span> <span class="o">/</span> <span class="n">other</span> <span class="c1"># implement some logic here</span>
<span class="k">def</span> <span class="nf">__div__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> <span class="c1"># Python 2 compatibility</span>
<span class="k">return</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="fm">__truediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">__itruediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span> <span class="o">//</span> <span class="n">other</span> <span class="c1"># implement some logic here</span>
<span class="k">def</span> <span class="nf">__idiv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> <span class="c1"># Python 2 compatibility</span>
<span class="k">return</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="fm">__itruediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
</pre></div>
</div>
<p>Special methods are looked up on the class and not on the instance to reflect
the behavior of the Python interpreter.</p>
</div>
</div>
<div class="section" id="s-writing-compatible-code-with-six">
<span id="writing-compatible-code-with-six"></span><h3>Writing compatible code with six<a class="headerlink" href="#writing-compatible-code-with-six" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="https://pythonhosted.org/six/">six</a> is the canonical compatibility library for supporting Python 2 and 3 in
a single codebase. Read its documentation!</p>
<p>A <a class="reference internal" href="#module-django.utils.six" title="django.utils.six"><code class="xref py py-mod docutils literal notranslate"><span class="pre">customized</span> <span class="pre">version</span> <span class="pre">of</span> <span class="pre">six</span></code></a> is bundled with Django
as of version 1.4.2. You can import it as <code class="docutils literal notranslate"><span class="pre">django.utils.six</span></code>.</p>
<p>Here are the most common changes required to write compatible code.</p>
<div class="section" id="s-string-handling-with-six">
<span id="s-id1"></span><span id="string-handling-with-six"></span><span id="id1"></span><h4>String handling<a class="headerlink" href="#string-handling-with-six" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">basestring</span></code> and <code class="docutils literal notranslate"><span class="pre">unicode</span></code> types were removed in Python 3, and the
meaning of <code class="docutils literal notranslate"><span class="pre">str</span></code> changed. To test these types, use the following idioms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">isinstance</span><span class="p">(</span><span class="n">myvalue</span><span class="p">,</span> <span class="n">six</span><span class="o">.</span><span class="n">string_types</span><span class="p">)</span> <span class="c1"># replacement for basestring</span>
<span class="nb">isinstance</span><span class="p">(</span><span class="n">myvalue</span><span class="p">,</span> <span class="n">six</span><span class="o">.</span><span class="n">text_type</span><span class="p">)</span> <span class="c1"># replacement for unicode</span>
<span class="nb">isinstance</span><span class="p">(</span><span class="n">myvalue</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">)</span> <span class="c1"># replacement for str</span>
</pre></div>
</div>
<p>Python ≥ 2.6 provides <code class="docutils literal notranslate"><span class="pre">bytes</span></code> as an alias for <code class="docutils literal notranslate"><span class="pre">str</span></code>, so you don’t need
<code class="xref py py-data docutils literal notranslate"><span class="pre">six.binary_type</span></code>.</p>
</div>
<div class="section" id="s-long">
<span id="long"></span><h4><code class="docutils literal notranslate"><span class="pre">long</span></code><a class="headerlink" href="#long" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">long</span></code> type no longer exists in Python 3. <code class="docutils literal notranslate"><span class="pre">1L</span></code> is a syntax error. Use
<code class="xref py py-data docutils literal notranslate"><span class="pre">six.integer_types</span></code> check if a value is an integer or a long:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">isinstance</span><span class="p">(</span><span class="n">myvalue</span><span class="p">,</span> <span class="n">six</span><span class="o">.</span><span class="n">integer_types</span><span class="p">)</span> <span class="c1"># replacement for (int, long)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-xrange">
<span id="xrange"></span><h4><code class="docutils literal notranslate"><span class="pre">xrange</span></code><a class="headerlink" href="#xrange" title="Permalink to this headline">¶</a></h4>
<p>If you use <code class="docutils literal notranslate"><span class="pre">xrange</span></code> on Python 2, import <code class="docutils literal notranslate"><span class="pre">six.moves.range</span></code> and use that
instead. You can also import <code class="docutils literal notranslate"><span class="pre">six.moves.xrange</span></code> (it’s equivalent to
<code class="docutils literal notranslate"><span class="pre">six.moves.range</span></code>) but the first technique allows you to simply drop the
import when dropping support for Python 2.</p>
</div>
<div class="section" id="s-moved-modules">
<span id="moved-modules"></span><h4>Moved modules<a class="headerlink" href="#moved-modules" title="Permalink to this headline">¶</a></h4>
<p>Some modules were renamed in Python 3. The <code class="docutils literal notranslate"><span class="pre">django.utils.six.moves</span></code>
module (based on the <code class="xref py py-mod docutils literal notranslate"><span class="pre">six.moves</span> <span class="pre">module</span></code>) provides a
compatible location to import them.</p>
</div>
<div class="section" id="s-py2">
<span id="py2"></span><h4><code class="docutils literal notranslate"><span class="pre">PY2</span></code><a class="headerlink" href="#py2" title="Permalink to this headline">¶</a></h4>
<p>If you need different code in Python 2 and Python 3, check <code class="xref py py-data docutils literal notranslate"><span class="pre">six.PY2</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">six</span><span class="o">.</span><span class="n">PY2</span><span class="p">:</span>
<span class="c1"># compatibility code for Python 2</span>
</pre></div>
</div>
<p>This is a last resort solution when <code class="xref py py-mod docutils literal notranslate"><span class="pre">six</span></code> doesn’t provide an appropriate
function.</p>
<span class="target" id="module-django.utils.six"></span></div>
</div>
<div class="section" id="s-django-customized-version-of-six">
<span id="django-customized-version-of-six"></span><h3>Django customized version of <code class="docutils literal notranslate"><span class="pre">six</span></code><a class="headerlink" href="#django-customized-version-of-six" title="Permalink to this headline">¶</a></h3>
<p>The version of six bundled with Django (<code class="docutils literal notranslate"><span class="pre">django.utils.six</span></code>) includes a few
customizations for internal use only.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Porting to Python 3</a><ul>
<li><a class="reference internal" href="#philosophy">Philosophy</a></li>
<li><a class="reference internal" href="#porting-tips">Porting tips</a><ul>
<li><a class="reference internal" href="#unicode-literals">Unicode literals</a></li>
<li><a class="reference internal" href="#string-handling">String handling</a></li>
<li><a class="reference internal" href="#str-and-unicode-methods"><code class="docutils literal notranslate"><span class="pre">__str__()</span></code> and <code class="docutils literal notranslate"><span class="pre">__unicode__()</span></code> methods</a></li>
<li><a class="reference internal" href="#dict-and-dict-like-classes"><code class="docutils literal notranslate"><span class="pre">dict</span></code> and <code class="docutils literal notranslate"><span class="pre">dict</span></code>-like classes</a></li>
<li><a class="reference internal" href="#httprequest-and-httpresponse-objects"><code class="docutils literal notranslate"><span class="pre">HttpRequest</span></code> and <code class="docutils literal notranslate"><span class="pre">HttpResponse</span></code> objects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#coding-guidelines">Coding guidelines</a><ul>
<li><a class="reference internal" href="#syntax-requirements">Syntax requirements</a><ul>
<li><a class="reference internal" href="#unicode">Unicode</a></li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#magic-methods">Magic methods</a><ul>
<li><a class="reference internal" href="#iterators">Iterators</a></li>
<li><a class="reference internal" href="#boolean-evaluation">Boolean evaluation</a></li>
<li><a class="reference internal" href="#division">Division</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-compatible-code-with-six">Writing compatible code with six</a><ul>
<li><a class="reference internal" href="#string-handling-with-six">String handling</a></li>
<li><a class="reference internal" href="#long"><code class="docutils literal notranslate"><span class="pre">long</span></code></a></li>
<li><a class="reference internal" href="#xrange"><code class="docutils literal notranslate"><span class="pre">xrange</span></code></a></li>
<li><a class="reference internal" href="#moved-modules">Moved modules</a></li>
<li><a class="reference internal" href="#py2"><code class="docutils literal notranslate"><span class="pre">PY2</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#django-customized-version-of-six">Django customized version of <code class="docutils literal notranslate"><span class="pre">six</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="pagination.html"
title="previous chapter">Pagination</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="security.html"
title="next chapter">Security in Django</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/topics/python3.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 11, 2019</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="pagination.html" title="Pagination">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="security.html" title="Security in Django">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
