Welcome to the__future__¶

The top of everypy file should include the following:

from__future__import(absolute_import,division,print_function,unicode_literals)importsix

This will make the Python 2 interpreter behave as close to Python 3 aspossible.

All matplotlib files should also importsix, whether they are usingit or not, just to make moving code between modules easier, assixgets useda lot.

Finding places to use six¶

The only way to make sure code works on both Python 2 and 3 is to make sure itis covered by unit tests.

However, the2to3 commandline tool can also be used to locate placesthat require special handling withsix.

(Themodernize tool mayalso be handy, though I’ve never used it personally).

Thesix documentation serves as agood reference for the sorts of things that need to be updated.

The dreaded\u escapes¶

Whenfrom__future__importunicode_literals is used, all stringliterals (not preceded with ab) will become unicode literals.

Normally, one would use “raw” string literals to encode strings thatcontain a lot of slashes that we don’t want Python to interpret asspecial characters. A common example in matplotlib is when it dealswith TeX and has to represent things liker"\usepackage{foo}".Unfortunately, on Python 2there is no way to representu in a rawunicode string literal, since it will always be interpreted as thestart of a unicode character escape, such asu20af. The onlysolution is to use a regular (non-raw) string literal and repeat allslashes, e.g."\\usepackage{foo}".

The following shows the problem on Python 2:

>>>ur'\u'  File"<stdin>", line1SyntaxError:(unicode error) 'rawunicodeescape' codec can't decode bytes inposition 0-1: truncated \uXXXX>>>ur'\\u'u'\\\\u'>>>u'\u'  File"<stdin>", line1SyntaxError:(unicode error) 'unicodeescape' codec can't decode bytes inposition 0-1: truncated \uXXXX escape>>>u'\\u'u'\\u'

This bug has been fixed in Python 3, however, we can’t take advantageof that and still support Python 2:

>>>r'\u''\\u'>>>r'\\u''\\\\u'>>>'\u'  File"<stdin>", line1SyntaxError:(unicode error) 'unicodeescape' codec can't decode bytes inposition 0-1: truncated \uXXXX escape>>>'\\u''\\u'

Iteration¶

The behavior of the methods for iterating over the items, values andkeys of a dictionary has changed in Python 3. Additionally, otherbuilt-in functions such aszip,range andmap have changed toreturn iterators rather than temporary lists.

In many cases, the performance implications of iterating vs. creatinga temporary list won’t matter, so it’s tempting to use the form thatis simplest to read. However, that results in code that behavesdifferently on Python 2 and 3, leading to subtle bugs that may not bedetected by the regression tests. Therefore, unless the loop inquestion is provably simple and doesn’t call into other code, thesix versions that ensure the same behavior on both Python 2 and 3should be used. The following table shows the mapping of equivalentsemantics between Python 2, 3 and six fordict.items():

Numpy-specific things¶

When specifying dtypes, all strings must be byte strings on Python 2and unicode strings on Python 3. The best way to handle this is toforce cast them usingstr(). The same is true of structurespecifiers in thestruct built-in module.