============================================
2to3: Python 3.0 source code conversion tool
============================================

This document describes :file:`2to3` -- a utility that converts Python 2.x code
to Python 3.0 code.

This utility remains under active development.

Overview
========

As covered in other documents, Python 3.0 breaks backwards compatibility
with Python 2.x. In other words, there is *no guarantee* that code written for
Python 2.x will work correctly, or even at all, under Python 3.0. All existing
Python 2.x code will need to be rewritten to work with Python 3.0's new syntax.

Because this is a disruptive change, Python's developers have made an effort to
minimize the pain. It turns out a fair number of the syntax changes in Python
3.0 are "simple" enough that they can be applied to source code in an automated
way.

For example, Python 3.0 does not support the ``<>`` operator; it supports only
the ``!=`` operator::

    # Python 2.x syntax
    if a <> b:
        do_something()

    # Python 3.x syntax
    if a != b:
        do_something()

This change is simple enough that an automated code converter could alter the
code in a way that is always correct. Although it's not as easy as naively
replacing all occurrences of ``<>`` with ``!=`` (because that would include
occurrences of ``'<>'`` within strings), it's just a matter of parsing and
analyzing source code to make the appropriate changes.

This, then, is the strategy and scope of :file:`2to3`. The :file:`2to3` tool
is capable of analyzing Python 2.x source code and suggesting *some*, but not
necessarily all, changes that need to be made in order for the code to work
with Python 3.0.

Of course, no automated tool of this sort can be perfect. Some of the Python
2.x-3.0 changes cannot be made reliably without human intervention, and others
can be made reliably in *most*, but not all, cases. :file:`2to3` will only make
changes that it can guarantee are 100 percent safe. The "Specific changes"
section of this document describes every change that :file:`2to3` knows how to
make with certainty, and the "Caveats" section describes every change that it
cannot make with certainty.

Specific changes
================

Caveats
=======