lib3to2 / README

Abstract
========

lib3to2 is a set of fixers that are intended to backport code written for
Python version 3.x into Python version 2.x.  The final target 2.x version is
the latest version of the 2.7 branch, as that is the last release in the Python
2.x branch.  Some attempts have been made, however, to make code compatible as
much as possible with versions of Python back to 2.5, and bug reports are still
welcome for Python features only present in 2.6+ that are not addressed by
lib3to2.

This project came about as a Google Summer of Code (TM) project in 2009.

Status
======

Because of the nature of the subject matter, 3to2 is not perfect, so check all
output manually.  3to2 does the bulk of the work, but there is code that simply
cannot be converted into a Python 2 equivalent for one reason or another.

3to2 will either produce working Python 2 code or warn about why it did not.
Any other behavior is a bug and should be reported.

lib3to2's fixers are somewhat well-tested individually, but there is no testing
that is done on interactions between multiple fixers, so most of the bugs in
the future will likely be found there.

Intention
=========

lib3to2 is intended to be a tool in the process of developing code that is
backwards-compatible between Python 3 and Python 2.  It is not intended to be a
complete solution for directly backporting Python 3 code, though it can often
be used for this purpose without issue.  Sufficiently large packages should be
developed with lib3to2 used throughout the process to avoid backwards-
incompatible code from becoming too embedded.

There are some features of Python 3 that have no equivalent in Python 2, and
though lib3to2 tries to fix as many of these as it can, some features are
beyond its grasp.  This is especially true of features not readily detectable
by their syntax alone and extremely subtle features, so make sure that code
using lib3to2 is thoroughly tested.

Repository
==========

lib3to2 resides at http://bitbucket.org/amentajo/lib3to2, where the bug tracker
can be found at http://bitbucket.org/amentajo/lib3to2/issues

Usage
=====

Run "./3to2" to convert stdin ("-"), files or directories given as
arguments.  By default, the tool outputs a unified diff-formatted patch on
standard output and a "what was changed" summary on standard error, but the
"-w" option can be given to write back converted files, creating
".bak"-named backup files.

If you are root, you can also install with "./setup.py build" and
"./setup.py install" ("make install" does this for you).

This branch of 3to2 must be run with Python 3.

To install locally (used for running tests as a non-privileged user), the
scripts assume you are using python3.1.  Modify accordingly if you are not.

Relationship with lib2to3
=========================

Some of the fixers for lib3to2 are directly copy-pasted from their 2to3
equivalent, with the element of PATTERN and the corresponding transformation
switched places.  Most fixers written for this program with a corresponding
2to3 fixer started from a clone of the 2to3 fixer, then modifying that fixer to
work in reverse.  I do not claim original authorship of these fixers, but I do
claim that they will work for 3to2, independent of how they work for 2to3.
In addition, this program depends on lib2to3 to implement fixers, test cases,
refactoring, and grammar.  Some portions of lib2to3 were modified to be more
generic to support lib3to2's calls.

You should use the latest version of lib2to3 from the Python sandbox rather
than the version (if any) that comes with Python.  As a convenience,
"two2three" from the Python Package Index is a recent enough version of lib2to3
renamed to avoid conflicts.  To use this package, replace all usage of
"lib2to3" with "two2three" within the 3to2 source files after installing
"two2three" from the PyPI.  Depending on the developer's mood, a version of
3to2 may be provided with this change already made.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.