Skip to content
Browse files

Update docs and bump version number for release

  • Loading branch information...
1 parent 43390ec commit c5142572b150573f33ea46e3c312cca7cae440e2 @bdarnell committed Dec 8, 2011
Showing with 37 additions and 23 deletions.
  1. +1 −0 .gitignore
  2. +27 −12 README.md
  3. +6 −10 auto2to3.py
  4. 0 bin/auto2to3
  5. +3 −1 setup.py
View
1 .gitignore
@@ -2,3 +2,4 @@
*~
build
dist
+MANIFEST
View
39 README.md
@@ -1,25 +1,40 @@
Overview
========
-`auto2to3` is a wrapper to run `2to3` automatically at import time. This is
-useful when developing a library that intends to support both Python 2 and
-Python 3 via `2to3`.
+`auto2to3` makes it easier and faster to use `2to3` to develop for
+Python 2 and 3 simultaneously. You can continue to work on the
+original 2.x code, and `auto2to3` converts modules to Python 3
+automatically at import time. `2to3` can be rather slow, so `auto2to3`
+caches its output between runs so it only needs to run `2to3` when the
+source files change.
Usage
=====
-`auto2to3.py --package=pkg main_module`
+Install `auto2to3` as usual using `pip`/`easy_install`. Note that `auto2to3`
+must be installed under Python 3 (it has only been tested with Python 3.2).
-main_module is run as if by the -m flag to the python interpreter
-(i.e. \_\_name\_\_ == '\_\_main\_\_'). All modules whose name begins with a name
-passed to the --package flag (which may be specified more than once)
-will be run through 2to3. 2to3 output is cached on disk between runs
-for speed.
+The `auto2to3` script supports a subset of the python interpreter's interface:
-Example
--------
+ auto2to3 -m mypackage.main_module
+ auto2to3 mypackage/script.py
-`auto2to3.py --package=tornado tornado.test.runtests`
+By default, all modules imported from a subdirectory of the current
+directory will be run through `2to3`. To change this behavior, use the
+`--package` or `--dir` flags to `auto2to3` to specify which packages or
+directories contain Python 2 code that should be converted.
+
+Finishing Touches
+=================
+
+`auto2to3` is a development tool; when you're ready to release a
+package that was developed with `auto2to3` you should use
+`setuptool`'s ability to run `2to3` as a part of the build process.
+In your `setup.py` file, simply `import setuptools` and pass
+`use_2to3=True` as a keyword argument to the `setup()` function.
+Don't forget to remove or exclude `auto2to3`'s cache files from the
+distribution (add `global-exclude _auto2to3*` to `MANIFEST.in`, and
+add a similar pattern to your `.gitignore` or equivalent)
Acknowledgements
================
View
16 auto2to3.py
@@ -2,17 +2,13 @@
"""Wrapper to run 2to3 automatically at import time.
Usage:
- auto2to3.py main_module
+ auto2to3 -m mypackage.main_module
+ auto2to3 mypackage/script.py
-main_module is run as if by the -m flag to the python interpreter
-(i.e. __name__ == '__main__'). It must be specified as a module name,
-not a filename (e.g. tornado.test.runtests, not tornado/test/runtests.py)
-
-All modules whose name begins wtih a prefix passed to the --package or --dir
-flags (which may be specified more than once) will be run through 2to3.
---package is compared to the python module name, while --dir uses the path
-in the filesystem. If neither --package or --dir is specified, the current
-directory is assumed, which is often sufficient.
+By default, all modules imported from a subdirectory of the current
+directory will be run through `2to3`. To change this behavior, use the
+`--package` or `--dir` flags to `auto2to3` to specify which packages or
+directories contain Python 2 code that should be converted.
2to3 output is cached on disk between runs for speed.
View
0 bin/auto2to3 100644 → 100755
File mode changed.
View
4 setup.py
@@ -1,9 +1,11 @@
from distutils.core import setup
setup(name="auto2to3",
- version="0.2",
+ version="0.3",
author="Ben Darnell",
url="https://github.com/bdarnell/auto2to3/",
py_modules=["auto2to3"],
scripts=["bin/auto2to3"],
+ license="http://www.apache.org/licenses/LICENSE-2.0",
+ description="Wrapper to run 2to3 automatically at import time",
)

0 comments on commit c514257

Please sign in to comment.
Something went wrong with that request. Please try again.