~dkuhlman/python-training-materials/Materials

<span id="pyporting-howto"></span><h1>Porting Python 2 Code to Python 3<a class="headerlink" href="#porting-python-2-code-to-python-3" title="Permalink to this headline">¶</a></h1>

<tr class="field-odd field"><th class="field-name">author:</th><td class="field-body">Brett Cannon</td>

100

</tr>

101

</tbody>

102

</table>

103

104

<p class="topic-title first">Abstract</p>

105

<p>With Python 3 being the future of Python while Python 2 is still in active

106

use, it is good to have your project available for both major releases of

107

Python. This guide is meant to help you figure out how best to support both

108

Python 2 & 3 simultaneously.</p>

109

<p>If you are looking to port an extension module instead of pure Python code,

110

please see <a class="reference internal" href="cporting.html#cporting-howto"><span>Porting Extension Modules to Python 3</span></a>.</p>

111

<p>If you would like to read one core Python developer’s take on why Python 3

112

came into existence, you can read Nick Coghlan’s <a class="reference external" href="https://ncoghlan-devs-python-notes.readthedocs.org/en/latest/python3/questions_and_answers.html">Python 3 Q & A</a>.</p>

113

<p>For help with porting, you can email the <a class="reference external" href="https://mail.python.org/mailman/listinfo/python-porting">python-porting</a> mailing list with

114

questions.</p>

115

</div>

116

117

<h2>The Short Explanation<a class="headerlink" href="#the-short-explanation" title="Permalink to this headline">¶</a></h2>

118

<p>To make your project be single-source Python 2/3 compatible, the basic steps

119

are:</p>

120

121

<li>Only worry about supporting Python 2.7</li>

122

<li>Make sure you have good test coverage (<a class="reference external" href="https://pypi.python.org/pypi/coverage">coverage.py</a> can help;

123

<code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">coverage</span></code>)</li>

124

<li>Learn the differences between Python 2 & 3</li>

125

<li>Use <a class="reference external" href="https://python-modernize.readthedocs.org/en/latest/">Modernize</a> or <a class="reference external" href="http://python-future.org/automatic_conversion.html">Futurize</a> to update your code (<code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">modernize</span></code> or

126

<code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">future</span></code>, respectively)</li>

127

<li>Use <a class="reference external" href="https://pypi.python.org/pypi/pylint">Pylint</a> to help make sure you don’t regress on your Python 3 support

128

(<code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pylint</span></code>)</li>

129

<li>Use <a class="reference external" href="https://pypi.python.org/pypi/caniusepython3">caniusepython3</a> to find out which of your dependencies are blocking your

130

use of Python 3 (<code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">caniusepython3</span></code>)</li>

131

<li>Once your dependencies are no longer blocking you, use continuous integration

132

to make sure you stay compatible with Python 2 & 3 (<a class="reference external" href="https://pypi.python.org/pypi/tox">tox</a> can help test

133

against multiple versions of Python; <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">tox</span></code>)</li>

134

</ol>

135

<p>If you are dropping support for Python 2 entirely, then after you learn the

136

differences between Python 2 & 3 you can run <a class="reference external" href="https://docs.python.org/3/library/2to3.html">2to3</a> over your code and skip the

137

rest of the steps outlined above.</p>

138

</div>

139

140

<h2>Details<a class="headerlink" href="#details" title="Permalink to this headline">¶</a></h2>

141

<p>A key point about supporting Python 2 & 3 simultaneously is that you can start

142

<strong>today</strong>! Even if your dependencies are not supporting Python 3 yet that does

143

not mean you can’t modernize your code <strong>now</strong> to support Python 3. Most changes

144

required to support Python 3 lead to cleaner code using newer practices even in

145

Python 2.</p>

146

<p>Another key point is that modernizing your Python 2 code to also support

147

Python 3 is largely automated for you. While you might have to make some API

148

decisions thanks to Python 3 clarifying text data versus binary data, the

149

lower-level work is now mostly done for you and thus can at least benefit from

150

the automated changes immediately.</p>

151

<p>Keep those key points in mind while you read on about the details of porting

152

your code to support Python 2 & 3 simultaneously.</p>

153

154

<h3>Drop support for Python 2.6 and older<a class="headerlink" href="#drop-support-for-python-2-6-and-older" title="Permalink to this headline">¶</a></h3>

155

<p>While you can make Python 2.5 work with Python 3, it is <strong>much</strong> easier if you

156

only have to work with Python 2.7. If dropping Python 2.5 is not an

157

option then the <a class="reference external" href="https://pypi.python.org/pypi/six">six</a> project can help you support Python 2.5 & 3 simultaneously

158

(<code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">six</span></code>). Do realize, though, that nearly all the projects listed

159

in this HOWTO will not be available to you.</p>

160

<p>If you are able to skip Python 2.5 and older, then the required changes

161

to your code should continue to look and feel like idiomatic Python code. At

162

worst you will have to use a function instead of a method in some instances or

163

have to import a function instead of using a built-in one, but otherwise the

164

overall transformation should not feel foreign to you.</p>

165

<p>But you should aim for only supporting Python 2.7. Python 2.6 is no longer

166

supported and thus is not receiving bugfixes. This means <strong>you</strong> will have to

167

work around any issues you come across with Python 2.6. There are also some

168

tools mentioned in this HOWTO which do not support Python 2.6 (e.g., <a class="reference external" href="https://pypi.python.org/pypi/pylint">Pylint</a>),

169

and this will become more commonplace as time goes on. It will simply be easier

170

for you if you only support the versions of Python that you have to support.</p>

171

</div>

172

173

<h3>Make sure you specify the proper version support in your <code class="docutils literal"><span class="pre">setup.py</span></code> file<a class="headerlink" href="#make-sure-you-specify-the-proper-version-support-in-your-setup-py-file" title="Permalink to this headline">¶</a></h3>

174

<p>In your <code class="docutils literal"><span class="pre">setup.py</span></code> file you should have the proper <a class="reference external" href="https://pypi.python.org/pypi?%3Aaction=list_classifiers">trove classifier</a>

175

specifying what versions of Python you support. As your project does not support

176

Python 3 yet you should at least have

177

<code class="docutils literal"><span class="pre">Programming</span> <span class="pre">Language</span> <span class="pre">::</span> <span class="pre">Python</span> <span class="pre">::</span> <span class="pre">2</span> <span class="pre">::</span> <span class="pre">Only</span></code> specified. Ideally you should

178

also specify each major/minor version of Python that you do support, e.g.

179

180

</div>

181

182

<h3>Have good test coverage<a class="headerlink" href="#have-good-test-coverage" title="Permalink to this headline">¶</a></h3>

183

<p>Once you have your code supporting the oldest version of Python 2 you want it

184

to, you will want to make sure your test suite has good coverage. A good rule of

185

thumb is that if you want to be confident enough in your test suite that any

186

failures that appear after having tools rewrite your code are actual bugs in the

187

tools and not in your code. If you want a number to aim for, try to get over 80%

188

coverage (and don’t feel bad if you can’t easily get past 90%). If you

189

don’t already have a tool to measure test coverage then <a class="reference external" href="https://pypi.python.org/pypi/coverage">coverage.py</a> is

190

recommended.</p>

191

</div>

192

193

<h3>Learn the differences between Python 2 & 3<a class="headerlink" href="#learn-the-differences-between-python-2-3" title="Permalink to this headline">¶</a></h3>

194

<p>Once you have your code well-tested you are ready to begin porting your code to

195

Python 3! But to fully understand how your code is going to change and what

196

you want to look out for while you code, you will want to learn what changes

197

Python 3 makes in terms of Python 2. Typically the two best ways of doing that

198

is reading the <a class="reference external" href="https://docs.python.org/3/whatsnew/index.html">“What’s New”</a> doc for each release of Python 3 and the

199

<a class="reference external" href="http://python3porting.com/">Porting to Python 3</a> book (which is free online). There is also a handy

200

<a class="reference external" href="http://python-future.org/compatible_idioms.html">cheat sheet</a> from the Python-Future project.</p>

201

</div>

202

203

<h3>Update your code<a class="headerlink" href="#update-your-code" title="Permalink to this headline">¶</a></h3>

204

<p>Once you feel like you know what is different in Python 3 compared to Python 2,

205

it’s time to update your code! You have a choice between two tools in porting

206

your code automatically: <a class="reference external" href="https://python-modernize.readthedocs.org/en/latest/">Modernize</a> and <a class="reference external" href="http://python-future.org/automatic_conversion.html">Futurize</a>. Which tool you choose will

207

depend on how much like Python 3 you want your code to be. <a class="reference external" href="http://python-future.org/automatic_conversion.html">Futurize</a> does its

208

best to make Python 3 idioms and practices exist in Python 2, e.g. backporting

209

the <code class="docutils literal"><span class="pre">bytes</span></code> type from Python 3 so that you have semantic parity between the

210

major versions of Python. <a class="reference external" href="https://python-modernize.readthedocs.org/en/latest/">Modernize</a>,

211

on the other hand, is more conservative and targets a Python 2/3 subset of

212

Python, relying on <a class="reference external" href="https://pypi.python.org/pypi/six">six</a> to help provide compatibility.</p>

213

<p>Regardless of which tool you choose, they will update your code to run under

214

Python 3 while staying compatible with the version of Python 2 you started with.

215

Depending on how conservative you want to be, you may want to run the tool over

216

your test suite first and visually inspect the diff to make sure the

217

transformation is accurate. After you have transformed your test suite and

218

verified that all the tests still pass as expected, then you can transform your

219

application code knowing that any tests which fail is a translation failure.</p>

220

<p>Unfortunately the tools can’t automate everything to make your code work under

221

Python 3 and so there are a handful of things you will need to update manually

222

to get full Python 3 support (which of these steps are necessary vary between

223

the tools). Read the documentation for the tool you choose to use to see what it

224

fixes by default and what it can do optionally to know what will (not) be fixed

225

for you and what you may have to fix on your own (e.g. using <code class="docutils literal"><span class="pre">io.open()</span></code> over

226

the built-in <code class="docutils literal"><span class="pre">open()</span></code> function is off by default in Modernize). Luckily,

227

though, there are only a couple of things to watch out for which can be

228

considered large issues that may be hard to debug if not watched for.</p>

229

230

<h4>Division<a class="headerlink" href="#division" title="Permalink to this headline">¶</a></h4>

231

<p>In Python 3, <code class="docutils literal"><span class="pre">5</span> <span class="pre">/</span> <span class="pre">2</span> <span class="pre">==</span> <span class="pre">2.5</span></code> and not <code class="docutils literal"><span class="pre">2</span></code>; all division between <code class="docutils literal"><span class="pre">int</span></code> values

232

result in a <code class="docutils literal"><span class="pre">float</span></code>. This change has actually been planned since Python 2.2

233

which was released in 2002. Since then users have been encouraged to add

234

<code class="docutils literal"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span> <span class="pre">division</span></code> to any and all files which use the <code class="docutils literal"><span class="pre">/</span></code> and

235

<code class="docutils literal"><span class="pre">//</span></code> operators or to be running the interpreter with the <code class="docutils literal"><span class="pre">-Q</span></code> flag. If you

236

have not been doing this then you will need to go through your code and do two

237

things:</p>

238

239

<li>Add <code class="docutils literal"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span> <span class="pre">division</span></code> to your files</li>

240

<li>Update any division operator as necessary to either use <code class="docutils literal"><span class="pre">//</span></code> to use floor

241

division or continue using <code class="docutils literal"><span class="pre">/</span></code> and expect a float</li>

242

</ol>

243

<p>The reason that <code class="docutils literal"><span class="pre">/</span></code> isn’t simply translated to <code class="docutils literal"><span class="pre">//</span></code> automatically is that if

244

an object defines a <code class="docutils literal"><span class="pre">__truediv__</span></code> method but not <code class="docutils literal"><span class="pre">__floordiv__</span></code> then your

245

code would begin to fail (e.g. a user-defined class that uses <code class="docutils literal"><span class="pre">/</span></code> to

246

signify some operation but not <code class="docutils literal"><span class="pre">//</span></code> for the same thing or at all).</p>

247

</div>

248

249

<h4>Text versus binary data<a class="headerlink" href="#text-versus-binary-data" title="Permalink to this headline">¶</a></h4>

250

<p>In Python 2 you could use the <code class="docutils literal"><span class="pre">str</span></code> type for both text and binary data.

251

Unfortunately this confluence of two different concepts could lead to brittle

252

code which sometimes worked for either kind of data, sometimes not. It also

253

could lead to confusing APIs if people didn’t explicitly state that something

254

that accepted <code class="docutils literal"><span class="pre">str</span></code> accepted either text or binary data instead of one

255

specific type. This complicated the situation especially for anyone supporting

256

multiple languages as APIs wouldn’t bother explicitly supporting <code class="docutils literal"><span class="pre">unicode</span></code>

257

when they claimed text data support.</p>

258

<p>To make the distinction between text and binary data clearer and more

259

pronounced, Python 3 did what most languages created in the age of the internet

260

have done and made text and binary data distinct types that cannot blindly be

261

mixed together (Python predates widespread access to the internet). For any code

262

that only deals with text or only binary data, this separation doesn’t pose an

263

issue. But for code that has to deal with both, it does mean you might have to

264

now care about when you are using text compared to binary data, which is why

265

this cannot be entirely automated.</p>

266

<p>To start, you will need to decide which APIs take text and which take binary

267

(it is <strong>highly</strong> recommended you don’t design APIs that can take both due to

268

the difficulty of keeping the code working; as stated earlier it is difficult to

269

do well). In Python 2 this means making sure the APIs that take text can work

270

with <code class="docutils literal"><span class="pre">unicode</span></code> in Python 2 and those that work with binary data work with the

271

<code class="docutils literal"><span class="pre">bytes</span></code> type from Python 3 and thus a subset of <code class="docutils literal"><span class="pre">str</span></code> in Python 2 (which the

272

<code class="docutils literal"><span class="pre">bytes</span></code> type in Python 2 is an alias for). Usually the biggest issue is

273

realizing which methods exist for which types in Python 2 & 3 simultaneously

274

(for text that’s <code class="docutils literal"><span class="pre">unicode</span></code> in Python 2 and <code class="docutils literal"><span class="pre">str</span></code> in Python 3, for binary

275

that’s <code class="docutils literal"><span class="pre">str</span></code>/<code class="docutils literal"><span class="pre">bytes</span></code> in Python 2 and <code class="docutils literal"><span class="pre">bytes</span></code> in Python 3). The following

276

table lists the <strong>unique</strong> methods of each data type across Python 2 & 3

277

(e.g., the <code class="docutils literal"><span class="pre">decode()</span></code> method is usable on the equivalent binary data type in

278

either Python 2 or 3, but it can’t be used by the text data type consistently

279

between Python 2 and 3 because <code class="docutils literal"><span class="pre">str</span></code> in Python 3 doesn’t have the method). Do

280

note that as of Python 3.5 the <code class="docutils literal"><span class="pre">__mod__</span></code> method was added to the bytes type.</p>

281

282

283

284

285

</colgroup>

286

287

288

<td><strong>Binary data</strong></td>

289

</tr>

290

291

<td>decode</td>

292

</tr>

293

<tr class="row-odd"><td>encode</td>

294

295

</tr>

296

<tr class="row-even"><td>format</td>

297

298

</tr>

299

<tr class="row-odd"><td>isdecimal</td>

300

301

</tr>

302

<tr class="row-even"><td>isnumeric</td>

303

304

</tr>

305

</tbody>

306

</table>

307

<p>Making the distinction easier to handle can be accomplished by encoding and

308

decoding between binary data and text at the edge of your code. This means that

309

when you receive text in binary data, you should immediately decode it. And if

310

your code needs to send text as binary data then encode it as late as possible.

311

This allows your code to work with only text internally and thus eliminates

312

having to keep track of what type of data you are working with.</p>

313

<p>The next issue is making sure you know whether the string literals in your code

314

represent text or binary data. At minimum you should add a <code class="docutils literal"><span class="pre">b</span></code> prefix to any

315

literal that presents binary data. For text you should either use the

316

<code class="docutils literal"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span> <span class="pre">unicode_literals</span></code> statement or add a <code class="docutils literal"><span class="pre">u</span></code> prefix to

317

the text literal.</p>

318

<p>As part of this dichotomy you also need to be careful about opening files.

319

Unless you have been working on Windows, there is a chance you have not always

320

bothered to add the <code class="docutils literal"><span class="pre">b</span></code> mode when opening a binary file (e.g., <code class="docutils literal"><span class="pre">rb</span></code> for

321

binary reading). Under Python 3, binary files and text files are clearly

322

distinct and mutually incompatible; see the <a class="reference internal" href="../library/io.html#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal"><span class="pre">io</span></code></a> module for details.

323

Therefore, you <strong>must</strong> make a decision of whether a file will be used for

324

binary access (allowing binary data to be read and/or written) or text access

325

(allowing text data to be read and/or written). You should also use <a class="reference internal" href="../library/io.html#io.open" title="io.open"><code class="xref py py-func docutils literal"><span class="pre">io.open()</span></code></a>

326

for opening files instead of the built-in <a class="reference internal" href="../library/functions.html#open" title="open"><code class="xref py py-func docutils literal"><span class="pre">open()</span></code></a> function as the <a class="reference internal" href="../library/io.html#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal"><span class="pre">io</span></code></a>

327

module is consistent from Python 2 to 3 while the built-in <a class="reference internal" href="../library/functions.html#open" title="open"><code class="xref py py-func docutils literal"><span class="pre">open()</span></code></a> function

328

is not (in Python 3 it’s actually <a class="reference internal" href="../library/io.html#io.open" title="io.open"><code class="xref py py-func docutils literal"><span class="pre">io.open()</span></code></a>).</p>

329

<p>The constructors of both <code class="docutils literal"><span class="pre">str</span></code> and <code class="docutils literal"><span class="pre">bytes</span></code> have different semantics for the

330

same arguments between Python 2 & 3. Passing an integer to <code class="docutils literal"><span class="pre">bytes</span></code> in Python 2

331

will give you the string representation of the integer: <code class="docutils literal"><span class="pre">bytes(3)</span> <span class="pre">==</span> <span class="pre">'3'</span></code>.

332

But in Python 3, an integer argument to <code class="docutils literal"><span class="pre">bytes</span></code> will give you a bytes object

333

as long as the integer specified, filled with null bytes:

334

<code class="docutils literal"><span class="pre">bytes(3)</span> <span class="pre">==</span> <span class="pre">b'\x00\x00\x00'</span></code>. A similar worry is necessary when passing a

335

bytes object to <code class="docutils literal"><span class="pre">str</span></code>. In Python 2 you just get the bytes object back:

336

<code class="docutils literal"><span class="pre">str(b'3')</span> <span class="pre">==</span> <span class="pre">b'3'</span></code>. But in Python 3 you get the string representation of the

337

bytes object: <code class="docutils literal"><span class="pre">str(b'3')</span> <span class="pre">==</span> <span class="pre">"b'3'"</span></code>.</p>

338

<p>Finally, the indexing of binary data requires careful handling (slicing does

339

<strong>not</strong> require any special handling). In Python 2,

340

<code class="docutils literal"><span class="pre">b'123'[1]</span> <span class="pre">==</span> <span class="pre">b'2'</span></code> while in Python 3 <code class="docutils literal"><span class="pre">b'123'[1]</span> <span class="pre">==</span> <span class="pre">50</span></code>. Because binary data

341

is simply a collection of binary numbers, Python 3 returns the integer value for

342

the byte you index on. But in Python 2 because <code class="docutils literal"><span class="pre">bytes</span> <span class="pre">==</span> <span class="pre">str</span></code>, indexing

343

returns a one-item slice of bytes. The <a class="reference external" href="https://pypi.python.org/pypi/six">six</a> project has a function

344

named <code class="docutils literal"><span class="pre">six.indexbytes()</span></code> which will return an integer like in Python 3:

345

<code class="docutils literal"><span class="pre">six.indexbytes(b'123',</span> <span class="pre">1)</span></code>.</p>

346

<p>To summarize:</p>

347

348

<li>Decide which of your APIs take text and which take binary data</li>

349

<li>Make sure that your code that works with text also works with <code class="docutils literal"><span class="pre">unicode</span></code> and

350

code for binary data works with <code class="docutils literal"><span class="pre">bytes</span></code> in Python 2 (see the table above

351

for what methods you cannot use for each type)</li>

352

<li>Mark all binary literals with a <code class="docutils literal"><span class="pre">b</span></code> prefix, use a <code class="docutils literal"><span class="pre">u</span></code> prefix or

353

<a class="reference internal" href="../library/__future__.html#module-__future__" title="__future__: Future statement definitions"><code class="xref py py-mod docutils literal"><span class="pre">__future__</span></code></a> import statement for text literals</li>

354

<li>Decode binary data to text as soon as possible, encode text as binary data as

355

late as possible</li>

356

<li>Open files using <a class="reference internal" href="../library/io.html#io.open" title="io.open"><code class="xref py py-func docutils literal"><span class="pre">io.open()</span></code></a> and make sure to specify the <code class="docutils literal"><span class="pre">b</span></code> mode when

357

appropriate</li>

358

<li>Be careful when indexing binary data</li>

359

</ol>

360

</div>

361

362

<h4>Use feature detection instead of version detection<a class="headerlink" href="#use-feature-detection-instead-of-version-detection" title="Permalink to this headline">¶</a></h4>

363

<p>Inevitably you will have code that has to choose what to do based on what

364

version of Python is running. The best way to do this is with feature detection

365

of whether the version of Python you’re running under supports what you need.

366

If for some reason that doesn’t work then you should make the version check is

367

against Python 2 and not Python 3. To help explain this, let’s look at an

368

example.</p>

369

<p>Let’s pretend that you need access to a feature of <a class="reference external" href="https://docs.python.org/3/library/importlib.html#module-importlib">importlib</a> that

370

is available in Python’s standard library since Python 3.3 and available for

371

Python 2 through <a class="reference external" href="https://pypi.python.org/pypi/importlib2">importlib2</a> on PyPI. You might be tempted to write code to

372

access e.g. the <code class="docutils literal"><span class="pre">importlib.abc</span></code> module by doing the following:</p>

373

<div class="highlight-python3"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>

374

375

<span class="k">if</span> <span class="n">sys</span><span class="o">.</span><span class="n">version_info</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="mi">3</span><span class="p">:</span>

376

<span class="kn">from</span> <span class="nn">importlib</span> <span class="k">import</span> <span class="n">abc</span>

377

378

<span class="kn">from</span> <span class="nn">importlib2</span> <span class="k">import</span> <span class="n">abc</span>

379

</pre></div>

380

</div>

381

<p>The problem with this code is what happens when Python 4 comes out? It would

382

be better to treat Python 2 as the exceptional case instead of Python 3 and

383

assume that future Python versions will be more compatible with Python 3 than

384

Python 2:</p>

385

<div class="highlight-python3"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>

386

387

<span class="k">if</span> <span class="n">sys</span><span class="o">.</span><span class="n">version_info</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">></span> <span class="mi">2</span><span class="p">:</span>

388

<span class="kn">from</span> <span class="nn">importlib</span> <span class="k">import</span> <span class="n">abc</span>

389

390

<span class="kn">from</span> <span class="nn">importlib2</span> <span class="k">import</span> <span class="n">abc</span>

391

</pre></div>

392

</div>

393

<p>The best solution, though, is to do no version detection at all and instead rely

394

on feature detection. That avoids any potential issues of getting the version

395

detection wrong and helps keep you future-compatible:</p>

396

397

<span class="kn">from</span> <span class="nn">importlib</span> <span class="k">import</span> <span class="n">abc</span>

398

<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>

399

<span class="kn">from</span> <span class="nn">importlib2</span> <span class="k">import</span> <span class="n">abc</span>

400

</pre></div>

401

</div>

402

</div>

403

</div>

404

405

<h3>Prevent compatibility regressions<a class="headerlink" href="#prevent-compatibility-regressions" title="Permalink to this headline">¶</a></h3>

406

<p>Once you have fully translated your code to be compatible with Python 3, you

407

will want to make sure your code doesn’t regress and stop working under

408

Python 3. This is especially true if you have a dependency which is blocking you

409

from actually running under Python 3 at the moment.</p>

410

<p>To help with staying compatible, any new modules you create should have

411

at least the following block of code at the top of it:</p>

412

<div class="highlight-python3"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">absolute_import</span>

413

<span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">division</span>

414

<span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">print_function</span>

415

<span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">unicode_literals</span>

416

</pre></div>

417

</div>

418

<p>You can also run Python 2 with the <code class="docutils literal"><span class="pre">-3</span></code> flag to be warned about various

419

compatibility issues your code triggers during execution. If you turn warnings

420

into errors with <code class="docutils literal"><span class="pre">-Werror</span></code> then you can make sure that you don’t accidentally

421

miss a warning.</p>

422

<p>You can also use the <a class="reference external" href="https://pypi.python.org/pypi/pylint">Pylint</a> project and its <code class="docutils literal"><span class="pre">--py3k</span></code> flag to lint your code

423

to receive warnings when your code begins to deviate from Python 3

424

compatibility. This also prevents you from having to run <a class="reference external" href="https://python-modernize.readthedocs.org/en/latest/">Modernize</a> or <a class="reference external" href="http://python-future.org/automatic_conversion.html">Futurize</a>

425

over your code regularly to catch compatibility regressions. This does require

426

you only support Python 2.7 and Python 3.4 or newer as that is Pylint’s

427

minimum Python version support.</p>

428

</div>

429

430

<h3>Check which dependencies block your transition<a class="headerlink" href="#check-which-dependencies-block-your-transition" title="Permalink to this headline">¶</a></h3>

431

<p><strong>After</strong> you have made your code compatible with Python 3 you should begin to

432

care about whether your dependencies have also been ported. The <a class="reference external" href="https://pypi.python.org/pypi/caniusepython3">caniusepython3</a>

433

project was created to help you determine which projects

434

– directly or indirectly – are blocking you from supporting Python 3. There

435

is both a command-line tool as well as a web interface at

436

<a class="reference external" href="https://caniusepython3.com">https://caniusepython3.com</a> .</p>

437

<p>The project also provides code which you can integrate into your test suite so

438

that you will have a failing test when you no longer have dependencies blocking

439

you from using Python 3. This allows you to avoid having to manually check your

440

dependencies and to be notified quickly when you can start running on Python 3.</p>

441

</div>

442

443

<h3>Update your <code class="docutils literal"><span class="pre">setup.py</span></code> file to denote Python 3 compatibility<a class="headerlink" href="#update-your-setup-py-file-to-denote-python-3-compatibility" title="Permalink to this headline">¶</a></h3>

444

<p>Once your code works under Python 3, you should update the classifiers in

445

your <code class="docutils literal"><span class="pre">setup.py</span></code> to contain <code class="docutils literal"><span class="pre">Programming</span> <span class="pre">Language</span> <span class="pre">::</span> <span class="pre">Python</span> <span class="pre">::</span> <span class="pre">3</span></code> and to not

446

specify sole Python 2 support. This will tell

447

anyone using your code that you support Python 2 <strong>and</strong> 3. Ideally you will

448

also want to add classifiers for each major/minor version of Python you now

449

support.</p>

450

</div>

451

452

<h3>Use continuous integration to stay compatible<a class="headerlink" href="#use-continuous-integration-to-stay-compatible" title="Permalink to this headline">¶</a></h3>

453

<p>Once you are able to fully run under Python 3 you will want to make sure your

454

code always works under both Python 2 & 3. Probably the best tool for running

455

your tests under multiple Python interpreters is <a class="reference external" href="https://pypi.python.org/pypi/tox">tox</a>. You can then integrate

456

tox with your continuous integration system so that you never accidentally break

457

Python 2 or 3 support.</p>

458

<p>You may also want to use the <code class="docutils literal"><span class="pre">-bb</span></code> flag with the Python 3 interpreter to

459

trigger an exception when you are comparing bytes to strings or bytes to an int

460

(the latter is available starting in Python 3.5). By default type-differing

461

comparisons simply return <code class="docutils literal"><span class="pre">False</span></code>, but if you made a mistake in your

462

separation of text/binary data handling or indexing on bytes you wouldn’t easily

463

find the mistake. This flag will raise an exception when these kinds of

464

comparisons occur, making the mistake much easier to track down.</p>

465

<p>And that’s mostly it! At this point your code base is compatible with both

466

Python 2 and 3 simultaneously. Your testing will also be set up so that you

467

don’t accidentally break Python 2 or 3 compatibility regardless of which version

468

you typically run your tests under while developing.</p>

469

</div>

470

</div>

471

472

<h2>Dropping Python 2 support completely<a class="headerlink" href="#dropping-python-2-support-completely" title="Permalink to this headline">¶</a></h2>

473

<p>If you are able to fully drop support for Python 2, then the steps required

474

to transition to Python 3 simplify greatly.</p>

475

476

<li>Update your code to only support Python 2.7</li>

477

<li>Make sure you have good test coverage (<a class="reference external" href="https://pypi.python.org/pypi/coverage">coverage.py</a> can help)</li>

478

<li>Learn the differences between Python 2 & 3</li>

479

<li>Use <a class="reference external" href="https://docs.python.org/3/library/2to3.html">2to3</a> to rewrite your code to run only under Python 3</li>

480

</ol>

481

<p>After this your code will be fully Python 3 compliant but in a way that is not

482

supported by Python 2. You should also update the classifiers in your

483

<code class="docutils literal"><span class="pre">setup.py</span></code> to contain <code class="docutils literal"><span class="pre">Programming</span> <span class="pre">Language</span> <span class="pre">::</span> <span class="pre">Python</span> <span class="pre">::</span> <span class="pre">3</span> <span class="pre">::</span> <span class="pre">Only</span></code>.</p>

484

</div>

485

</div>

486

487

488

</div>

489

</div>

490

</div>

491

492

493

<h3><a href="../contents.html">Table Of Contents</a></h3>

494

<ul>

495

<li><a class="reference internal" href="#">Porting Python 2 Code to Python 3</a><ul>

496

<li><a class="reference internal" href="#the-short-explanation">The Short Explanation</a></li>

497

<li><a class="reference internal" href="#details">Details</a><ul>

498

<li><a class="reference internal" href="#drop-support-for-python-2-6-and-older">Drop support for Python 2.6 and older</a></li>

499

<li><a class="reference internal" href="#make-sure-you-specify-the-proper-version-support-in-your-setup-py-file">Make sure you specify the proper version support in your <code class="docutils literal"><span class="pre">setup.py</span></code> file</a></li>

500

<li><a class="reference internal" href="#have-good-test-coverage">Have good test coverage</a></li>

501

<li><a class="reference internal" href="#learn-the-differences-between-python-2-3">Learn the differences between Python 2 & 3</a></li>

502

<li><a class="reference internal" href="#update-your-code">Update your code</a><ul>

503

<li><a class="reference internal" href="#division">Division</a></li>

504

<li><a class="reference internal" href="#text-versus-binary-data">Text versus binary data</a></li>

505

<li><a class="reference internal" href="#use-feature-detection-instead-of-version-detection">Use feature detection instead of version detection</a></li>

506

</ul>

507

</li>

508

<li><a class="reference internal" href="#prevent-compatibility-regressions">Prevent compatibility regressions</a></li>

509

<li><a class="reference internal" href="#check-which-dependencies-block-your-transition">Check which dependencies block your transition</a></li>

510

<li><a class="reference internal" href="#update-your-setup-py-file-to-denote-python-3-compatibility">Update your <code class="docutils literal"><span class="pre">setup.py</span></code> file to denote Python 3 compatibility</a></li>

511

<li><a class="reference internal" href="#use-continuous-integration-to-stay-compatible">Use continuous integration to stay compatible</a></li>

512

</ul>

513

</li>

514

<li><a class="reference internal" href="#dropping-python-2-support-completely">Dropping Python 2 support completely</a></li>

515

</ul>

516

</li>

517

</ul>

518

519

<h4>Previous topic</h4>

520

<p class="topless"><a href="index.html"

521

title="previous chapter">Python HOWTOs</a></p>

522

<h4>Next topic</h4>

523

<p class="topless"><a href="cporting.html"

524

title="next chapter">Porting Extension Modules to Python 3</a></p>

525

526

527

528

<li><a href="../bugs.html">Report a Bug</a></li>

529

<li><a href="../_sources/howto/pyporting.txt"

530

rel="nofollow">Show Source</a></li>

531

</ul>

532

</div>

533

</div>

534

</div>

535

536

</div>

537

538

<h3>Navigation</h3>

539

<ul>

540

541

<a href="../genindex.html" title="General Index"

542

>index</a></li>

543

544

<a href="../py-modindex.html" title="Python Module Index"

545

>modules</a> |</li>

546

547

<a href="cporting.html" title="Porting Extension Modules to Python 3"

548

>next</a> |</li>

549

550

<a href="index.html" title="Python HOWTOs"

551

>previous</a> |</li>

552

<li><img src="../_static/py.png" alt=""

553

style="vertical-align: middle; margin-top: -1px"/></li>

554

<li><a href="https://www.python.org/">Python</a> »</li>

555

<li>

556

557

<a href="../index.html">Documentation </a> »

558

</li>

559

560

<li class="nav-item nav-item-1"><a href="index.html" >Python HOWTOs</a> »</li>

561

562

563

564

565

566

567

568

569

570

</form>

571

</div>

572

573

574

</li>

575

576

</ul>

577

</div>

578

579

580

<br />

581

The Python Software Foundation is a non-profit corporation.

582

<a href="https://www.python.org/psf/donations/">Please donate.</a>

583

<br />

584

Last updated on Sep 23, 2016.

585

<a href="../bugs.html">Found a bug</a>?

586

<br />

587

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

588

</div>

589

590

</body>

591

</html>

b'\\ No newline at end of file'

Older »