Using 2to3¶

2to3 will usually be installed with the Python interpreter as a script. It isalso located in theTools/scripts directory of the Python root.

2to3’s basic arguments are a list of files or directories to transform. Thedirectories are recursively traversed for Python sources.

Here is a sample Python 2.x source file,example.py:

defgreet(name):print"Hello,{0}!".format(name)print"What's your name?"name=raw_input()greet(name)

It can be converted to Python 3.x code via 2to3 on the command line:

$2to3example.py

A diff against the original source file is printed. 2to3 can also write theneeded modifications right back to the source file. (A backup of the originalfile is made unless-n is also given.) Writing the changes back isenabled with the-w flag:

$2to3-wexample.py

After transformation,example.py looks like this:

defgreet(name):print("Hello,{0}!".format(name))print("What's your name?")name=input()greet(name)

Comments and exact indentation are preserved throughout the translation process.

By default, 2to3 runs a set ofpredefined fixers. The-l flag lists all available fixers. An explicit set of fixers to runcan be given with-f. Likewise the-x explicitly disables afixer. The following example runs only theimports andhas_key fixers:

$2to3-fimports-fhas_keyexample.py

This command runs every fixer except theapply fixer:

$2to3-xapplyexample.py

Some fixers areexplicit, meaning they aren’t run by default and must belisted on the command line to be run. Here, in addition to the default fixers,theidioms fixer is run:

$2to3-fall-fidiomsexample.py

Notice how passingall enables all default fixers.

Sometimes 2to3 will find a place in your source code that needs to be changed,but 2to3 cannot fix automatically. In this case, 2to3 will print a warningbeneath the diff for a file. You should address the warning in order to havecompliant 3.x code.

2to3 can also refactor doctests. To enable this mode, use the-dflag. Note thatonly doctests will be refactored. This also doesn’t requirethe module to be valid Python. For example, doctest like examples in a reSTdocument could also be refactored with this option.

The-v option enables output of more information on the translationprocess.

Since some print statements can be parsed as function calls or statements, 2to3cannot always read files containing the print function. When 2to3 detects thepresence of thefrom__future__importprint_function compiler directive, itmodifies its internal grammar to interpretprint() as a function. Thischange can also be enabled manually with the-p flag. Use-p to run fixers on code that already has had its print statementsconverted. Also-e can be used to makeexec() a function.

The-o or--output-dir option allows specification of analternate directory for processed output files to be written to. The-n flag is required when using this as backup files do not make sensewhen not overwriting the input files.

The-W or--write-unchanged-files flag tells 2to3 to alwayswrite output files even if no changes were required to the file. This is mostuseful with-o so that an entire Python source tree is copied withtranslation from one directory to another.This option implies the-w flag as it would not make sense otherwise.

The--add-suffix option specifies a string to append to all outputfilenames. The-n flag is required when specifying this as backupsare not necessary when writing to different filenames. Example:

$2to3-n-W--add-suffix=3example.py

Will cause a converted file namedexample.py3 to be written.

To translate an entire project from one directory tree to another use:

$2to3--output-dir=python3-version/mycode-W-npython2-version/mycode

Fixers¶

Each step of transforming code is encapsulated in a fixer. The command2to3-l lists them. Asdocumented above, each can be turned onand off individually. They are described here in more detail.

apply¶

Removes usage ofapply(). For exampleapply(function,*args,**kwargs) is converted tofunction(*args,**kwargs).

asserts¶

Replaces deprecatedunittest method names with the correct ones.

From	To
failUnlessEqual(a,b)	assertEqual(a,b)
assertEquals(a,b)	assertEqual(a,b)
failIfEqual(a,b)	assertNotEqual(a,b)
assertNotEquals(a,b)	assertNotEqual(a,b)
failUnless(a)	assertTrue(a)
assert_(a)	assertTrue(a)
failIf(a)	assertFalse(a)
failUnlessRaises(exc,cal)	assertRaises(exc,cal)
failUnlessAlmostEqual(a,b)	assertAlmostEqual(a,b)
assertAlmostEquals(a,b)	assertAlmostEqual(a,b)
failIfAlmostEqual(a,b)	assertNotAlmostEqual(a,b)
assertNotAlmostEquals(a,b)	assertNotAlmostEqual(a,b)

basestring¶

Convertsbasestring tostr.

buffer¶

Convertsbuffer tomemoryview. This fixer is optionalbecause thememoryview API is similar but not exactly the same asthat ofbuffer.

dict¶

Fixes dictionary iteration methods.dict.iteritems() is converted todict.items(),dict.iterkeys() todict.keys(), anddict.itervalues() todict.values(). Similarly,dict.viewitems(),dict.viewkeys() anddict.viewvalues() areconverted respectively todict.items(),dict.keys() anddict.values(). It also wraps existing usages ofdict.items(),dict.keys(), anddict.values() in a call tolist.

except¶

ConvertsexceptX,T toexceptXasT.

exec¶

Converts theexec statement to theexec() function.

execfile¶

Removes usage ofexecfile(). The argument toexecfile() iswrapped in calls toopen(),compile(), andexec().

exitfunc¶

Changes assignment ofsys.exitfunc to use of theatexitmodule.

filter¶

Wrapsfilter() usage in alist call.

funcattrs¶

Fixes function attributes that have been renamed. For example,my_function.func_closure is converted tomy_function.__closure__.

future¶

Removesfrom__future__importnew_feature statements.

getcwdu¶

Renamesos.getcwdu() toos.getcwd().

has_key¶

Changesdict.has_key(key) tokeyindict.

idioms¶

This optional fixer performs several transformations that make Python codemore idiomatic. Type comparisons liketype(x)isSomeClass andtype(x)==SomeClass are converted toisinstance(x,SomeClass).while1 becomeswhileTrue. This fixer also tries to make use ofsorted() in appropriate places. For example, this block

L=list(some_iterable)L.sort()

is changed to

L=sorted(some_iterable)

import¶

Detects sibling imports and converts them to relative imports.

imports¶

Handles module renames in the standard library.

imports2¶

Handles other modules renames in the standard library. It is separate fromtheimports fixer only because of technical limitations.

input¶

Convertsinput(prompt) toeval(input(prompt)).

intern¶

Convertsintern() tosys.intern().

isinstance¶

Fixes duplicate types in the second argument ofisinstance(). Forexample,isinstance(x,(int,int)) is converted toisinstance(x,int) andisinstance(x,(int,float,int)) is converted toisinstance(x,(int,float)).

itertools_imports¶

Removes imports ofitertools.ifilter(),itertools.izip(), anditertools.imap(). Imports ofitertools.ifilterfalse() are alsochanged toitertools.filterfalse().

itertools¶

Changes usage ofitertools.ifilter(),itertools.izip(), anditertools.imap() to their built-in equivalents.itertools.ifilterfalse() is changed toitertools.filterfalse().

long¶

Renameslong toint.

map¶

Wrapsmap() in alist call. It also changesmap(None,x)tolist(x). Usingfromfuture_builtinsimportmap disables thisfixer.

metaclass¶

Converts the old metaclass syntax (__metaclass__=Meta in the classbody) to the new (classX(metaclass=Meta)).

methodattrs¶

Fixes old method attribute names. For example,meth.im_func is convertedtometh.__func__.

ne¶

Converts the old not-equal syntax,<>, to!=.

next¶

Converts the use of iterator’snext() methods to thenext() function. It also renamesnext() methods to__next__().

nonzero¶

Renames definitions of methods called__nonzero__()to__bool__().

numliterals¶

Converts octal literals into the new syntax.

operator¶

Converts calls to various functions in theoperator module to other,but equivalent, function calls. When needed, the appropriateimportstatements are added, e.g.importcollections.abc. The following mappingare made:

From	To
operator.isCallable(obj)	callable(obj)
operator.sequenceIncludes(obj)	operator.contains(obj)
operator.isSequenceType(obj)	isinstance(obj,collections.abc.Sequence)
operator.isMappingType(obj)	isinstance(obj,collections.abc.Mapping)
operator.isNumberType(obj)	isinstance(obj,numbers.Number)
operator.repeat(obj,n)	operator.mul(obj,n)
operator.irepeat(obj,n)	operator.imul(obj,n)

paren¶

Add extra parenthesis where they are required in list comprehensions. Forexample,[xforxin1,2] becomes[xforxin(1,2)].

print¶

Converts theprint statement to theprint() function.

raise¶

ConvertsraiseE,V toraiseE(V), andraiseE,V,T toraiseE(V).with_traceback(T). IfE is a tuple, the translation will beincorrect because substituting tuples for exceptions has been removed in 3.0.

raw_input¶

Convertsraw_input() toinput().

reduce¶

Handles the move ofreduce() tofunctools.reduce().

reload¶

Convertsreload() toimportlib.reload().

renames¶

Changessys.maxint tosys.maxsize.

repr¶

Replaces backtick repr with therepr() function.

set_literal¶

Replaces use of theset constructor with set literals. This fixeris optional.

standarderror¶

RenamesStandardError toException.

sys_exc¶

Changes the deprecatedsys.exc_value,sys.exc_type,sys.exc_traceback to usesys.exc_info().

throw¶

Fixes the API change in generator’sthrow() method.

tuple_params¶

Removes implicit tuple parameter unpacking. This fixer inserts temporaryvariables.

types¶

Fixes code broken from the removal of some members in thetypesmodule.

unicode¶

Renamesunicode tostr.

urllib¶

Handles the rename ofurllib andurllib2 to theurllibpackage.

ws_comma¶

Removes excess whitespace from comma separated items. This fixer isoptional.

xrange¶

Renamesxrange() torange() and wraps existingrange()calls withlist.

xreadlines¶

Changesforxinfile.xreadlines() toforxinfile.

zip¶

Wrapszip() usage in alist call. This is disabled whenfromfuture_builtinsimportzip appears.

lib2to3 — 2to3’s library¶

Source code:Lib/lib2to3/