cpython/Doc/library/2to3.rst

110 lines
3.8 KiB
ReStructuredText
Raw Normal View History

2008-07-23 23:45:37 -03:00
.. _2to3-reference:
2to3 - Automated Python 2 to 3 code translation
===============================================
2009-01-11 15:48:15 -04:00
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>
2008-07-23 23:45:37 -03:00
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 :mod:`lib2to3` is, however, a flexible and generic library, so it is
possible to write your own fixers for 2to3. :mod:`lib2to3` could also be
adapted to custom applications in which Python code needs to be edited
automatically.
2008-07-23 23:45:37 -03:00
Using 2to3
----------
2to3 will usually be installed with the Python interpreter as a script. It is
also located in the :file:`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.
2008-07-23 23:45:37 -03:00
Here is a sample Python 2.x source file, :file:`example.py`::
def greet(name):
2008-07-24 04:09:21 -03:00
print "Hello, {0}!".format(name)
2008-07-23 23:45:37 -03:00
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. (Of course, a backup of the
2008-10-19 16:39:16 -03:00
original is also be made unless :option:`-n` is also given.) Writing the
changes back is enabled with the :option:`-w` flag::
2008-07-23 23:45:37 -03:00
$ 2to3 -w example.py
After transformation, :file:`example.py` looks like this::
2008-07-23 23:45:37 -03:00
def greet(name):
2008-07-25 18:59:53 -03:00
print("Hello, {0}!".format(name))
2008-07-23 23:45:37 -03:00
print("What's your name?")
name = input()
greet(name)
2008-10-22 18:05:30 -03:00
Comments and exact indentation are preserved throughout the translation process.
2008-07-23 23:45:37 -03:00
2008-10-13 18:51:40 -03:00
By default, 2to3 runs a set of predefined fixers. The :option:`-l` flag lists
2008-10-22 17:57:43 -03:00
all available fixers. An explicit set of fixers to run can be given with
2008-10-13 18:51:40 -03:00
:option:`-f`. Likewise the :option:`-x` explicitly disables a fixer. The
following example runs only the ``imports`` and ``has_key`` fixers::
2008-07-23 23:45:37 -03:00
$ 2to3 -f imports -f has_key example.py
2008-10-13 18:51:40 -03:00
This command runs every fixer except the ``apply`` fixer::
$ 2to3 -x apply example.py
2008-10-22 17:57:43 -03:00
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::
2008-07-23 23:45:37 -03:00
$ 2to3 -f all -f idioms example.py
Notice how passing ``all`` enables all default fixers.
2008-07-23 23:45:37 -03:00
2008-10-22 17:57:43 -03:00
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 :option:`-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.
2008-10-13 18:51:40 -03:00
The :option:`-v` option enables output of more information on the translation
process.
2008-09-16 18:20:28 -03:00
When the :option:`-p` is passed, 2to3 treats ``print`` as a function instead of
a statement. This is useful when ``from __future__ import print_function`` is
being used. If this option is not given, the print fixer will surround print
calls in an extra set of parentheses because it cannot differentiate between the
2008-10-22 17:57:43 -03:00
print statement with parentheses (such as ``print ("a" + "b" + "c")``) and a
2008-09-16 18:20:28 -03:00
true function call.
2008-07-23 23:45:37 -03:00
:mod:`lib2to3` - 2to3's library
-------------------------------
.. module:: lib2to3
:synopsis: the 2to3 library
.. moduleauthor:: Guido van Rossum
.. moduleauthor:: Collin Winter
.. warning::
The :mod:`lib2to3` API should be considered unstable and may change
drastically in the future.
2008-07-23 23:45:37 -03:00
.. XXX What is the public interface anyway?