
2to3 - Automated Python 2 to 3 code translation
***********************************************

2to3 is a Python program that reads Python 2.x source code and applies
a series of *fixers* to transform it into valid Python 3.x code.  The
standard library contains a rich set of fixers that will handle almost
all code.  2to3 supporting library ``lib2to3`` is, however, a flexible
and generic library, so it is possible to write your own fixers for
2to3.  ``lib2to3`` could also be adapted to custom applications in
which Python code needs to be edited automatically.


Using 2to3
==========

2to3 will usually be installed with the Python interpreter as a
script.  It is also located in the ``Tools/scripts`` directory of the
Python root.

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

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

   def greet(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:

   $ 2to3 example.py

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

   $ 2to3 -w example.py

After transformation, ``example.py`` looks like this:

   def greet(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 of predefined fixers.  The *-l* flag lists
all available fixers.  An explicit set of fixers to run can be given
with *-f*.  Likewise the *-x* explicitly disables a fixer.  The
following example runs only the ``imports`` and ``has_key`` fixers:

   $ 2to3 -f imports -f has_key example.py

This command runs every fixer except the ``apply`` fixer:

   $ 2to3 -x apply example.py

Some fixers are *explicit*, meaning they aren't run by default and
must be listed on the command line to be run.  Here, in addition to
the default fixers, the ``idioms`` fixer is run:

   $ 2to3 -f all -f idioms example.py

Notice how passing ``all`` 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 warning beneath the diff for a file.  You should address the
warning in order to have compliant 3.x code.

2to3 can also refactor doctests.  To enable this mode, use the *-d*
flag.  Note that *only* doctests will be refactored.  This also
doesn't require the module to be valid Python.  For example, doctest
like examples in a reST document could also be refactored with this
option.

The *-v* option enables output of more information on the translation
process.


``lib2to3`` - 2to3's library
============================

Note: The ``lib2to3`` API should be considered unstable and may change
  drastically in the future.
