1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
|
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Should I import unicode_literals? — Python-Future documentation</title>
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/my-styles.css" type="text/css" />
<link rel="stylesheet" href="_static/bootswatch-3.3.4/cerulean/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.3.4/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
<link rel="shortcut icon" href="_static/python-future-icon-32.ico"/>
<link rel="top" title="Python-Future documentation" href="index.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-19344199-2']);
_gaq.push(['_trackPageview']);
</script>
</head>
<body role="document">
<a href="https://github.com/PythonCharmers/python-future"><img style="position: absolute; top: 45px; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>
<div id="navbar" class="navbar navbar-inverse navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="logo"> <img height="32" width="32" src="_static/python-future-logo-textless-transparent.png" /></a>
<a class="navbar-brand" href="index.html">Python-Future</a>
<span class="navbar-text navbar-version pull-left"><b></b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="overview.html">Overview</a></li>
<li><a href="compatible_idioms.html">Cheat Sheet</a></li>
<li><a href="faq.html">FAQ</a></li>
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="index.html">Contents <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc"><ul>
<li class="toctree-l1"><a class="reference internal" href="whatsnew.html">What’s New</a><ul>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-15-0-2015-07-25">What’s new in version 0.15.0 (2015-07-25)</a></li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-14-3-2014-12-15">What’s new in version 0.14.3 (2014-12-15)</a></li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-14-2-2014-11-21">What’s new in version 0.14.2 (2014-11-21)</a></li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-14-1-2014-10-02">What’s new in version 0.14.1 (2014-10-02)</a></li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-14-2014-10-02">What’s new in version 0.14 (2014-10-02)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="whatsnew.html#bug-fixes">Bug fixes</a></li>
<li class="toctree-l3"><a class="reference internal" href="whatsnew.html#internal-cleanups">Internal cleanups</a></li>
<li class="toctree-l3"><a class="reference internal" href="whatsnew.html#deprecations">Deprecations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#previous-versions">Previous versions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview: Easy, clean, reliable Python 2/3 compatibility</a><ul>
<li class="toctree-l2"><a class="reference internal" href="overview.html#features">Features</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#code-examples">Code examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#automatic-conversion-to-py2-3-compatible-code">Automatic conversion to Py2/3-compatible code</a><ul>
<li class="toctree-l3"><a class="reference internal" href="overview.html#futurize-2-to-both">Futurize: 2 to both</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#automatic-translation">Automatic translation</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#licensing">Licensing</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick-start guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#if-you-are-writing-code-from-scratch">If you are writing code from scratch</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#to-convert-existing-python-3-code">To convert existing Python 3 code</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#to-convert-existing-python-2-code">To convert existing Python 2 code</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#standard-library-reorganization">Standard library reorganization</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#python-2-only-dependencies">Python 2-only dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="compatible_idioms.html">Cheat Sheet: Writing Python 2-3 compatible code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#setup">Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#essential-syntax-differences">Essential syntax differences</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#print">print</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#raising-exceptions">Raising exceptions</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#catching-exceptions">Catching exceptions</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#division">Division</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#long-integers">Long integers</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#octal-constants">Octal constants</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#backtick-repr">Backtick repr</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#metaclasses">Metaclasses</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#strings-and-bytes">Strings and bytes</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#unicode-text-string-literals">Unicode (text) string literals</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#byte-string-literals">Byte-string literals</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#basestring">basestring</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#unicode">unicode</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#stringio">StringIO</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#imports-relative-to-a-package">Imports relative to a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#dictionaries">Dictionaries</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#iterating-through-dict-keys-values-items">Iterating through <code class="docutils literal"><span class="pre">dict</span></code> keys/values/items</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#dict-keys-values-items-as-a-list">dict keys/values/items as a list</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#custom-class-behaviour">Custom class behaviour</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#custom-iterators">Custom iterators</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#custom-str-methods">Custom <code class="docutils literal"><span class="pre">__str__</span></code> methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#custom-nonzero-vs-bool-method">Custom <code class="docutils literal"><span class="pre">__nonzero__</span></code> vs <code class="docutils literal"><span class="pre">__bool__</span></code> method:</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#lists-versus-iterators">Lists versus iterators</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#xrange">xrange</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#range">range</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#map">map</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#imap">imap</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#zip-izip">zip, izip</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#filter-ifilter">filter, ifilter</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#other-builtins">Other builtins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#file-io-with-open">File IO with open()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#reduce">reduce()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#raw-input">raw_input()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#input">input()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#file">file()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#execfile">execfile()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#unichr">unichr()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#intern">intern()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#apply">apply()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#chr">chr()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#cmp">cmp()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#reload">reload()</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#standard-library">Standard library</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#dbm-modules">dbm modules</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#commands-subprocess-modules">commands / subprocess modules</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#subprocess-check-output">subprocess.check_output()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#collections-counter-and-ordereddict">collections: Counter and OrderedDict</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#stringio-module">StringIO module</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#http-module">http module</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#xmlrpc-module">xmlrpc module</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#html-escaping-and-entities">html escaping and entities</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#html-parsing">html parsing</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#urllib-module">urllib module</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#tkinter">Tkinter</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#socketserver">socketserver</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#copy-reg-copyreg">copy_reg, copyreg</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#configparser">configparser</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#queue">queue</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#repr-reprlib">repr, reprlib</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#userdict-userlist-userstring">UserDict, UserList, UserString</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#itertools-filterfalse-zip-longest">itertools: filterfalse, zip_longest</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="imports.html">Imports</a><ul>
<li class="toctree-l2"><a class="reference internal" href="imports.html#future-imports">__future__ imports</a></li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#imports-of-builtins">Imports of builtins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="imports.html#implicit-imports">Implicit imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="imports.html#explicit-imports">Explicit imports</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#standard-library-imports">Standard library imports</a><ul>
<li class="toctree-l3"><a class="reference internal" href="imports.html#direct-imports">Direct imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="imports.html#aliased-imports">Aliased imports</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#external-standard-library-backports">External standard-library backports</a></li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#included-full-backports">Included full backports</a></li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#using-python-2-only-dependencies-on-python-3">Using Python 2-only dependencies on Python 3</a></li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#should-i-import-unicode-literals">Should I import unicode_literals?</a><ul>
<li class="toctree-l3"><a class="reference internal" href="imports.html#benefits">Benefits</a></li>
<li class="toctree-l3"><a class="reference internal" href="imports.html#drawbacks">Drawbacks</a></li>
<li class="toctree-l3"><a class="reference internal" href="imports.html#others-perspectives">Others’ perspectives</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="what_else.html">What else you need to know</a><ul>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#bytes">bytes</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#str">str</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#dict">dict</a><ul>
<li class="toctree-l3"><a class="reference internal" href="what_else.html#memory-efficiency-and-alternatives">Memory-efficiency and alternatives</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#int">int</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#isinstance">isinstance</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#passing-data-to-from-python-2-libraries">Passing data to/from Python 2 libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#native-string-type">Native string type</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#open">open()</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#custom-str-methods">Custom __str__ methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#custom-iterators">Custom iterators</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#binding-a-method-to-a-class">Binding a method to a class</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#metaclasses">Metaclasses</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="automatic_conversion.html">Automatic conversion to Py2/3</a><ul>
<li class="toctree-l2"><a class="reference internal" href="automatic_conversion.html#futurize-py2-to-py2-3"><code class="docutils literal"><span class="pre">futurize</span></code>: Py2 to Py2/3</a><ul>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#stage-1-safe-fixes">Stage 1: “safe” fixes</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#stage-2-py3-style-code-with-wrappers-for-py2">Stage 2: Py3-style code with wrappers for Py2</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#separating-text-from-bytes">Separating text from bytes</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#post-conversion">Post-conversion</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="automatic_conversion.html#futurize-quick-start-guide"><code class="docutils literal"><span class="pre">futurize</span></code> quick-start guide</a><ul>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#step-0-setup">Step 0: setup</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#step-1-modern-py2-code">Step 1: modern Py2 code</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#step-2-working-py3-code-that-still-supports-py2">Step 2: working Py3 code that still supports Py2</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="automatic_conversion.html#pasteurize-py3-to-py2-3"><code class="docutils literal"><span class="pre">pasteurize</span></code>: Py3 to Py2/3</a></li>
<li class="toctree-l2"><a class="reference internal" href="automatic_conversion.html#known-limitations">Known limitations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions (FAQ)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="faq.html#who-is-this-for">Who is this for?</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#why-upgrade-to-python-3">Why upgrade to Python 3?</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#porting-philosophy">Porting philosophy</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#why-write-python-3-style-code">Why write Python 3-style code?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#can-t-i-just-roll-my-own-py2-3-compatibility-layer">Can’t I just roll my own Py2/3 compatibility layer?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#what-inspired-this-project">What inspired this project?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#maturity">Maturity</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#how-well-has-it-been-tested">How well has it been tested?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#is-the-api-stable">Is the API stable?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#relationship-between-python-future-and-other-compatibility-tools">Relationship between python-future and other compatibility tools</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#how-does-this-relate-to-2to3">How does this relate to <code class="docutils literal"><span class="pre">2to3</span></code>?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#can-i-maintain-a-python-2-codebase-and-use-2to3-to-automatically-convert-to-python-3-in-the-setup-script">Can I maintain a Python 2 codebase and use 2to3 to automatically convert to Python 3 in the setup script?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#what-is-the-relationship-between-future-and-six">What is the relationship between <code class="docutils literal"><span class="pre">future</span></code> and <code class="docutils literal"><span class="pre">six</span></code>?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#what-is-the-relationship-between-python-future-and-python-modernize">What is the relationship between <code class="docutils literal"><span class="pre">python-future</span></code> and <code class="docutils literal"><span class="pre">python-modernize</span></code>?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#platform-and-version-support">Platform and version support</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#which-versions-of-python-does-python-future-support">Which versions of Python does <code class="docutils literal"><span class="pre">python-future</span></code> support?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#support">Support</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#is-there-a-mailing-list">Is there a mailing list?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#contributing">Contributing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#can-i-help">Can I help?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#where-is-the-repo">Where is the repo?</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="stdlib_incompatibilities.html">Standard library incompatibilities</a><ul>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#array-array">array.array()</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#array-array-read">array.array.read()</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#base64-decodebytes-and-base64-encodebytes">base64.decodebytes() and base64.encodebytes()</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#re-ascii">re.ASCII</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#struct-pack">struct.pack()</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="older_interfaces.html">Older interfaces</a><ul>
<li class="toctree-l2"><a class="reference internal" href="older_interfaces.html#context-manager-for-import-hooks">Context-manager for import hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="older_interfaces.html#future-moves-interface"><code class="docutils literal"><span class="pre">future.moves</span></code> interface</a><ul>
<li class="toctree-l3"><a class="reference internal" href="older_interfaces.html#comparing-future-moves-and-six-moves">Comparing future.moves and six.moves</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="older_interfaces.html#import-and-from-import-functions"><code class="docutils literal"><span class="pre">import_</span></code> and <code class="docutils literal"><span class="pre">from_import</span></code> functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="older_interfaces.html#install-hooks-call">install_hooks() call</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changes in previous versions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-13-1-2014-09-23">Changes in version 0.13.1 (2014-09-23)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-13-2014-08-13">Changes in version 0.13 (2014-08-13)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#deprecations">Deprecations</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#new-features">New features</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#bug-fixes">Bug fixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-4-2014-07-18">Changes in version 0.12.4 (2014-07-18)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-3-2014-06-19">Changes in version 0.12.3 (2014-06-19)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-2-2014-05-25">Changes in version 0.12.2 (2014-05-25)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-1-2014-05-14">Changes in version 0.12.1 (2014-05-14)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-0-2014-05-06">Changes in version 0.12.0 (2014-05-06)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#more-robust-standard-library-import-hooks">More robust standard-library import hooks</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#newobject-base-object-defines-fallback-py2-compatible-special-methods"><code class="docutils literal"><span class="pre">newobject</span></code> base object defines fallback Py2-compatible special methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#past-builtins-module-improved"><code class="docutils literal"><span class="pre">past.builtins</span></code> module improved</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#surrogateescape-error-handler"><code class="docutils literal"><span class="pre">surrogateescape</span></code> error handler</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#newlist-type"><code class="docutils literal"><span class="pre">newlist</span></code> type</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#listvalues-and-listitems"><code class="docutils literal"><span class="pre">listvalues</span></code> and <code class="docutils literal"><span class="pre">listitems</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#tests">Tests</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#refactoring-of-future-standard-library-future-backports">Refactoring of <code class="docutils literal"><span class="pre">future.standard_library.*</span></code> -> <code class="docutils literal"><span class="pre">future.backports</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#backported-http-server-and-urllib-modules">Backported <code class="docutils literal"><span class="pre">http.server</span></code> and <code class="docutils literal"><span class="pre">urllib</span></code> modules</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#internal-refactoring">Internal refactoring</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#id1">Bug fixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-11-4-2014-05-25">Changes in version 0.11.4 (2014-05-25)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-11-3-2014-02-27">Changes in version 0.11.3 (2014-02-27)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#improved-compatibility-with-requests">Improved compatibility with <code class="docutils literal"><span class="pre">requests</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#conversion-scripts-explicitly-install-import-hooks">Conversion scripts explicitly install import hooks</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#futurize-script-no-longer-adds-unicode-literals-by-default"><code class="docutils literal"><span class="pre">futurize</span></code> script no longer adds <code class="docutils literal"><span class="pre">unicode_literals</span></code> by default</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-11-2014-01-28">Changes in version 0.11 (2014-01-28)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#past-package"><code class="docutils literal"><span class="pre">past</span></code> package</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#auto-translation-of-python-2-modules-upon-import">Auto-translation of Python 2 modules upon import</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#separate-pasteurize-script">Separate <code class="docutils literal"><span class="pre">pasteurize</span></code> script</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#pow">pow()</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#input-no-longer-disabled-globally-on-py2">input() no longer disabled globally on Py2</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#deprecated-feature-auto-installation-of-standard-library-import-hooks">Deprecated feature: auto-installation of standard-library import hooks</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#internal-changes">Internal changes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-10-2-2014-01-11">Changes in version 0.10.2 (2014-01-11)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#new-context-manager-interface-to-standard-library-hooks">New context-manager interface to standard_library hooks</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-10-0-2013-12-02">Changes in version 0.10.0 (2013-12-02)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#backported-dict-type">Backported <code class="docutils literal"><span class="pre">dict</span></code> type</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#utility-functions-raise-and-exec">Utility functions <code class="docutils literal"><span class="pre">raise_</span></code> and <code class="docutils literal"><span class="pre">exec_</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#bugfixes">Bugfixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-9-2013-11-06">Changes in version 0.9 (2013-11-06)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#isinstance-checks-are-supported-natively-with-backported-types"><code class="docutils literal"><span class="pre">isinstance</span></code> checks are supported natively with backported types</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#futurize-minimal-imports-by-default"><code class="docutils literal"><span class="pre">futurize</span></code>: minimal imports by default</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#looser-type-checking-for-the-backported-str-object">Looser type-checking for the backported <code class="docutils literal"><span class="pre">str</span></code> object</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#suspend-hooks-context-manager-added-to-future-standard-library">suspend_hooks() context manager added to <code class="docutils literal"><span class="pre">future.standard_library</span></code></a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-8-2013-10-28">Changes in version 0.8 (2013-10-28)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#python-2-6-support">Python 2.6 support</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#unused-modules-removed">Unused modules removed</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#isinstance-added-to-future-builtins-v0-8-2">isinstance() added to <code class="docutils literal"><span class="pre">future.builtins</span></code> (v0.8.2)</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#summary-of-all-changes">Summary of all changes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="credits.html">Licensing and credits</a><ul>
<li class="toctree-l2"><a class="reference internal" href="credits.html#licence">Licence</a></li>
<li class="toctree-l2"><a class="reference internal" href="credits.html#sponsor">Sponsor</a></li>
<li class="toctree-l2"><a class="reference internal" href="credits.html#authors">Authors</a><ul>
<li class="toctree-l3"><a class="reference internal" href="credits.html#development-lead">Development Lead</a></li>
<li class="toctree-l3"><a class="reference internal" href="credits.html#patches">Patches</a></li>
<li class="toctree-l3"><a class="reference internal" href="credits.html#suggestions-and-feedback">Suggestions and Feedback</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="credits.html#other-credits">Other Credits</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference (in progress)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-future.builtins">future.builtins Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-future.types">Backported types from Python 3</a><ul>
<li class="toctree-l3"><a class="reference internal" href="reference.html#for-more-information">For more information:</a></li>
<li class="toctree-l3"><a class="reference internal" href="reference.html#range">range()</a></li>
<li class="toctree-l3"><a class="reference internal" href="reference.html#super">super()</a></li>
<li class="toctree-l3"><a class="reference internal" href="reference.html#round">round()</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-future.standard_library">future.standard_library Interface</a><ul>
<li class="toctree-l3"><a class="reference internal" href="reference.html#limitations">Limitations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-future.utils">future.utils Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-past.builtins">past.builtins Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-past.types">Forward-ported types from Python 2</a></li>
</ul>
</li>
</ul>
</ul>
</li>
<li class="dropdown">
<a role="button"
id="dLabelLocalToc"
data-toggle="dropdown"
data-target="#"
href="#">Page <b class="caret"></b></a>
<ul class="dropdown-menu localtoc"
role="menu"
aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Should I import unicode_literals?</a><ul>
<li><a class="reference internal" href="#benefits">Benefits</a></li>
<li><a class="reference internal" href="#drawbacks">Drawbacks</a></li>
<li><a class="reference internal" href="#others-perspectives">Others’ perspectives</a><ul>
<li><a class="reference internal" href="#in-favour-of-unicode-literals">In favour of <code class="docutils literal"><span class="pre">unicode_literals</span></code></a></li>
<li><a class="reference internal" href="#against-unicode-literals">Against <code class="docutils literal"><span class="pre">unicode_literals</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</ul>
</li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3">
<div id="sidebar" class="bs-sidenav" role="complementary"><!--<h3>Python-Future</h3>
<p>-->
<h4>Easy, clean, reliable Python 2/3 compatibility</h4>
<a href="http://python-future.org">Table of Contents</a>
<!--
</p>
<h3>Other Formats</h3>
<p>
You can download the documentation in other formats as well:
</p>
<ul>
<li><a href="http://jinja.pocoo.org/docs/jinja-docs.pdf">as PDF</a>
<li><a href="http://jinja.pocoo.org/docs/jinja-docs.zip">as zipped HTML</a>
</ul>
-->
<!--<h3>Useful Links</h3>
<ul>
<li><a href="http://pypi.python.org/pypi/future">on PyPI</a></li>
<li><a href="https://github.com/PythonCharmers/python-future">on GitHub</a></li>
</ul>
--><ul>
<li class="toctree-l1"><a class="reference internal" href="whatsnew.html">What’s New</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview: Easy, clean, reliable Python 2/3 compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick-start guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="compatible_idioms.html">Cheat Sheet: Writing Python 2-3 compatible code</a></li>
<li class="toctree-l1"><a class="reference internal" href="imports.html">Imports</a></li>
<li class="toctree-l1"><a class="reference internal" href="what_else.html">What else you need to know</a></li>
<li class="toctree-l1"><a class="reference internal" href="automatic_conversion.html">Automatic conversion to Py2/3</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions (FAQ)</a></li>
<li class="toctree-l1"><a class="reference internal" href="stdlib_incompatibilities.html">Standard library incompatibilities</a></li>
<li class="toctree-l1"><a class="reference internal" href="older_interfaces.html">Older interfaces</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changes in previous versions</a></li>
<li class="toctree-l1"><a class="reference internal" href="credits.html">Licensing and credits</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference (in progress)</a></li>
</ul>
</div>
</div>
<div class="col-md-9">
<div class="section" id="should-i-import-unicode-literals">
<span id="unicode-literals"></span><h1>Should I import unicode_literals?<a class="headerlink" href="#should-i-import-unicode-literals" title="Permalink to this headline">¶</a></h1>
<p>The <code class="docutils literal"><span class="pre">future</span></code> package can be used with or without <code class="docutils literal"><span class="pre">unicode_literals</span></code>
imports.</p>
<p>In general, it is more compelling to use <code class="docutils literal"><span class="pre">unicode_literals</span></code> when
back-porting new or existing Python 3 code to Python 2/3 than when porting
existing Python 2 code to 2/3. In the latter case, explicitly marking up all
unicode string literals with <code class="docutils literal"><span class="pre">u''</span></code> prefixes would help to avoid
unintentionally changing the existing Python 2 API. However, if changing the
existing Python 2 API is not a concern, using <code class="docutils literal"><span class="pre">unicode_literals</span></code> may speed up
the porting process.</p>
<p>This section summarizes the benefits and drawbacks of using
<code class="docutils literal"><span class="pre">unicode_literals</span></code>. To avoid confusion, we recommend using
<code class="docutils literal"><span class="pre">unicode_literals</span></code> everywhere across a code-base or not at all, instead of
turning on for only some modules.</p>
<div class="section" id="benefits">
<h2>Benefits<a class="headerlink" href="#benefits" title="Permalink to this headline">¶</a></h2>
<ol class="arabic simple">
<li>String literals are unicode on Python 3. Making them unicode on Python 2
leads to more consistency of your string types across the two
runtimes. This can make it easier to understand and debug your code.</li>
<li>Code without <code class="docutils literal"><span class="pre">u''</span></code> prefixes is cleaner, one of the claimed advantages
of Python 3. Even though some unicode strings would require a function
call to invert them to native strings for some Python 2 APIs (see
<a class="reference internal" href="stdlib_incompatibilities.html#stdlib-incompatibilities"><span>Standard library incompatibilities</span></a>), the incidence of these function calls
would usually be much lower than the incidence of <code class="docutils literal"><span class="pre">u''</span></code> prefixes for text
strings in the absence of <code class="docutils literal"><span class="pre">unicode_literals</span></code>.</li>
<li>The diff when porting to a Python 2/3-compatible codebase may be smaller,
less noisy, and easier to review with <code class="docutils literal"><span class="pre">unicode_literals</span></code> than if an
explicit <code class="docutils literal"><span class="pre">u''</span></code> prefix is added to every unadorned string literal.</li>
<li>If support for Python 3.2 is required (e.g. for Ubuntu 12.04 LTS or
Debian wheezy), <code class="docutils literal"><span class="pre">u''</span></code> prefixes are a <code class="docutils literal"><span class="pre">SyntaxError</span></code>, making
<code class="docutils literal"><span class="pre">unicode_literals</span></code> the only option for a Python 2/3 compatible
codebase. [However, note that <code class="docutils literal"><span class="pre">future</span></code> doesn’t support Python 3.0-3.2.]</li>
</ol>
</div>
<div class="section" id="drawbacks">
<h2>Drawbacks<a class="headerlink" href="#drawbacks" title="Permalink to this headline">¶</a></h2>
<ol class="arabic simple">
<li>Adding <code class="docutils literal"><span class="pre">unicode_literals</span></code> to a module amounts to a “global flag day” for
that module, changing the data types of all strings in the module at once.
Cautious developers may prefer an incremental approach. (See
<a class="reference external" href="http://lwn.net/Articles/165039/">here</a> for an excellent article
describing the superiority of an incremental patch-set in the the case
of the Linux kernel.)</li>
</ol>
<ol class="arabic" start="2">
<li><p class="first">Changing to <code class="docutils literal"><span class="pre">unicode_literals</span></code> will likely introduce regressions on
Python 2 that require an initial investment of time to find and fix. The
APIs may be changed in subtle ways that are not immediately obvious.</p>
<p>An example on Python 2:</p>
<div class="highlight-python"><div class="highlight"><pre>### Module: mypaths.py
...
def unix_style_path(path):
return path.replace('\\', '/')
...
### User code:
>>> path1 = '\\Users\\Ed'
>>> unix_style_path(path1)
'/Users/ed'
</pre></div>
</div>
<p>On Python 2, adding a <code class="docutils literal"><span class="pre">unicode_literals</span></code> import to <code class="docutils literal"><span class="pre">mypaths.py</span></code> would
change the return type of the <code class="docutils literal"><span class="pre">unix_style_path</span></code> function from <code class="docutils literal"><span class="pre">str</span></code> to
<code class="docutils literal"><span class="pre">unicode</span></code> in the user code, which is difficult to anticipate and probably
unintended.</p>
<p>The counter-argument is that this code is broken, in a portability
sense; we see this from Python 3 raising a <code class="docutils literal"><span class="pre">TypeError</span></code> upon passing the
function a byte-string. The code needs to be changed to make explicit
whether the <code class="docutils literal"><span class="pre">path</span></code> argument is to be a byte string or a unicode string.</p>
</li>
<li><p class="first">With <code class="docutils literal"><span class="pre">unicode_literals</span></code> in effect, there is no way to specify a native
string literal (<code class="docutils literal"><span class="pre">str</span></code> type on both platforms). This can be worked around as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">unicode_literals</span>
<span class="gp">>>> </span><span class="o">...</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">future.utils</span> <span class="kn">import</span> <span class="n">bytes_to_native_str</span> <span class="k">as</span> <span class="n">n</span>
<span class="gp">>>> </span><span class="n">s</span> <span class="o">=</span> <span class="n">n</span><span class="p">(</span><span class="n">b</span><span class="s">'ABCD'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">s</span>
<span class="go">'ABCD' # on both Py2 and Py3</span>
</pre></div>
</div>
<p>although this incurs a performance penalty (a function call and, on Py3,
a <code class="docutils literal"><span class="pre">decode</span></code> method call.)</p>
<p>This is a little awkward because various Python library APIs (standard
and non-standard) require a native string to be passed on both Py2
and Py3. (See <a class="reference internal" href="stdlib_incompatibilities.html#stdlib-incompatibilities"><span>Standard library incompatibilities</span></a> for some examples. WSGI
dictionaries are another.)</p>
</li>
</ol>
<ol class="arabic" start="3">
<li><p class="first">If a codebase already explicitly marks up all text with <code class="docutils literal"><span class="pre">u''</span></code> prefixes,
and if support for Python versions 3.0-3.2 can be dropped, then
removing the existing <code class="docutils literal"><span class="pre">u''</span></code> prefixes and replacing these with
<code class="docutils literal"><span class="pre">unicode_literals</span></code> imports (the porting approach Django used) would
introduce more noise into the patch and make it more difficult to review.
However, note that the <code class="docutils literal"><span class="pre">futurize</span></code> script takes advantage of PEP 414 and
does not remove explicit <code class="docutils literal"><span class="pre">u''</span></code> prefixes that already exist.</p>
</li>
<li><p class="first">Turning on <code class="docutils literal"><span class="pre">unicode_literals</span></code> converts even docstrings to unicode, but
Pydoc breaks with unicode docstrings containing non-ASCII characters for
Python versions < 2.7.7. (<a class="reference external" href="http://bugs.python.org/issue1065986#msg207403">Fix
committed</a> in Jan 2014.):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
<span class="gp">... </span> <span class="s">u"Author: Martin von Löwis"</span>
<span class="gp">>>> </span><span class="n">help</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
<span class="go">/Users/schofield/Install/anaconda/python.app/Contents/lib/python2.7/pydoc.pyc in pipepager(text, cmd)</span>
<span class="go"> 1376 pipe = os.popen(cmd, 'w')</span>
<span class="go"> 1377 try:</span>
<span class="go">-> 1378 pipe.write(text)</span>
<span class="go"> 1379 pipe.close()</span>
<span class="go"> 1380 except IOError:</span>
<span class="go">UnicodeEncodeError: 'ascii' codec can't encode character u'\xf6' in position 71: ordinal not in range(128)</span>
</pre></div>
</div>
</li>
</ol>
<p>See <a class="reference external" href="http://stackoverflow.com/questions/809796/any-gotchas-using-unicode-literals-in-python-2-6">this Stack Overflow thread</a>
for other gotchas.</p>
</div>
<div class="section" id="others-perspectives">
<h2>Others’ perspectives<a class="headerlink" href="#others-perspectives" title="Permalink to this headline">¶</a></h2>
<div class="section" id="in-favour-of-unicode-literals">
<h3>In favour of <code class="docutils literal"><span class="pre">unicode_literals</span></code><a class="headerlink" href="#in-favour-of-unicode-literals" title="Permalink to this headline">¶</a></h3>
<p>Django recommends importing <code class="docutils literal"><span class="pre">unicode_literals</span></code> as its top <a class="reference external" href="https://docs.djangoproject.com/en/dev/topics/python3/#unicode-literals">porting tip</a> for
migrating Django extension modules to Python 3. The following <a class="reference external" href="https://groups.google.com/forum/#!topic/django-developers/2ddIWdicbNY">quote</a> is
from Aymeric Augustin on 23 August 2012 regarding why he chose
<code class="docutils literal"><span class="pre">unicode_literals</span></code> for the port of Django to a Python 2/3-compatible
codebase.:</p>
<blockquote>
<div><p>”... I’d like to explain why this PEP [PEP 414, which allows explicit
<code class="docutils literal"><span class="pre">u''</span></code> prefixes for unicode literals on Python 3.3+] is at odds with
the porting philosophy I’ve applied to Django, and why I would have
vetoed taking advantage of it.</p>
<p>“I believe that aiming for a Python 2 codebase with Python 3
compatibility hacks is a counter-productive way to port a project. You
end up with all the drawbacks of Python 2 (including the legacy <cite>u</cite>
prefixes) and none of the advantages Python 3 (especially the sane
string handling).</p>
<p>“Working to write Python 3 code, with legacy compatibility for Python
2, is much more rewarding. Of course it takes more effort, but the
results are much cleaner and much more maintainable. It’s really about
looking towards the future or towards the past.</p>
<p>“I understand the reasons why PEP 414 was proposed and why it was
accepted. It makes sense for legacy software that is minimally
maintained. I hope nobody puts Django in this category!”</p>
</div></blockquote>
</div>
<div class="section" id="against-unicode-literals">
<h3>Against <code class="docutils literal"><span class="pre">unicode_literals</span></code><a class="headerlink" href="#against-unicode-literals" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><p>“There are so many subtle problems that <code class="docutils literal"><span class="pre">unicode_literals</span></code> causes.
For instance lots of people accidentally introduce unicode into
filenames and that seems to work, until they are using it on a system
where there are unicode characters in the filesystem path.”</p>
<p class="attribution">—Armin Ronacher</p>
</div></blockquote>
<blockquote>
<div><p>“+1 from me for avoiding the unicode_literals future, as it can have
very strange side effects in Python 2.... This is one of the key
reasons I backed Armin’s PEP 414.”</p>
<p class="attribution">—Nick Coghlan</p>
</div></blockquote>
<blockquote>
<div><p>“Yeah, one of the nuisances of the WSGI spec is that the header values
IIRC are the str or StringType on both py2 and py3. With
unicode_literals this causes hard-to-spot bugs, as some WSGI servers
might be more tolerant than others, but usually using unicode in python
2 for WSGI headers will cause the response to fail.”</p>
<p class="attribution">—Antti Haapala</p>
</div></blockquote>
</div>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
© Copyright 2013-2015, Python Charmers Pty Ltd, Australia.<br/>
</p>
</div>
</footer>
<div class="footer">
<script type="text/javascript">
(function() {
var ga = document.createElement('script');
ga.src = ('https:' == document.location.protocol ?
'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
ga.setAttribute('async', 'true');
document.documentElement.firstChild.appendChild(ga);
})();
</script>
</div>
</body>
</html>
|
