Address issue #121: improve the 2to3 conversion experience.

README.md

@@ -40,6 +40,11 @@ Pystache is tested with--
 -   Python 3.1
 -   Python 3.2
 
+[Distribute](http://packages.python.org/distribute/) (the setuptools fork)
+is recommended over setuptools, and is required in some cases (e.g. for
+Python 3 support).  If you use [pip](http://www.pip-installer.org/),
+you probably already satisfy this requirement.
+
 JSON support is needed only for the command-line interface and to run
 the spec tests. We require simplejson for earlier versions of Python
 since Python's [json](http://docs.python.org/library/json.html) module
@@ -202,18 +207,37 @@ To run a subset of the tests, you can use
     pip install nose
     nosetests --tests pystache/tests/test_context.py:GetValueTests.test_dictionary__key_present
 
-**Running Pystache from source with Python 3.** Pystache is written in
-Python 2 and must be converted with
-[2to3](http://docs.python.org/library/2to3.html) prior to running under
-Python 3. The installation process (and tox) do this conversion
+### Using Python 3 with Pystache from source
+
+Pystache is written in Python 2 and must be converted to Python 3 prior to
+running under Python 3.  The installation process (and tox) do this
 automatically.
 
+To convert the source code to Python 3 (while using Python 3)--
+
+    python setup.py build
+
+And while using Python 2--
+
+    python setup.py --force2to3 build
+
+These commands write the converted code to a subdirectory called `build`.
+
+To do this manually (without using setup.py), you can use
+[2to3](http://docs.python.org/library/2to3.html) in two steps--
+
+    2to3 --write --nobackups --no-diffs --doctests_only pystache
+    2to3 --write --nobackups --no-diffs pystache
+
+This converts the code in-place.
+
 To `import pystache` from a source distribution while using Python 3, be
 sure that you are importing from a directory containing a converted
-version (e.g. from your site-packages directory after manually
-installing) and not from the original source directory. Otherwise, you
-will get a syntax error. You can help ensure this by not running the
-Python IDE from the project directory when importing Pystache.
+version (e.g. from the `build` directory after converting), and not from
+the unconverted source directory.  Otherwise, you will get a syntax error.
+You can help ensure this by not running the Python IDE from the project
+directory when importing Pystache.
+
 
 Mailing List
 ------------

setup.py

@@ -73,6 +73,8 @@ import shutil
 import sys
 
 
+OPTION_FORCE_2TO3 = '--force2to3'
+
 py_version = sys.version_info
 
 # distutils does not seem to support the following setup() arguments.
@@ -247,20 +249,6 @@ def convert_md_to_rst(path):
     return temp_path
 
 
-# We follow the guidance here for compatibility with using setuptools instead
-# of Distribute under Python 2 (on the subject of new, unrecognized keyword
-# arguments to setup()):
-#
-#   http://packages.python.org/distribute/python3.html#note-on-compatibility-with-setuptools
-#
-if py_version < (3, ):
-    extra = {}
-else:
-    extra = {
-        # Causes 2to3 to be run during the build step.
-        'use_2to3': True,
-    }
-
 # We use the package simplejson for older Python versions since Python
 # does not contain the module json before 2.6:
 #
@@ -291,12 +279,47 @@ PACKAGES = [
 ]
 
 
+def parse_args(sys_argv):
+    """
+    Modify sys_argv in place and return whether to force use of 2to3.
+
+    """
+    should_force2to3 = False
+    if len(sys_argv) > 1 and sys_argv[1] == OPTION_FORCE_2TO3:
+        sys_argv.pop(1)
+        should_force2to3 = True
+
+    return should_force2to3
+
+
+# The purpose of this function is to follow the guidance suggested here:
+#
+#   http://packages.python.org/distribute/python3.html#note-on-compatibility-with-setuptools
+#
+# The guidance is for better compatibility when using setuptools (e.g. with
+# earlier versions of Python 2) instead of Distribute, because of new
+# keyword arguments to setup() that setuptools may not recognize.
+def get_extra_args(should_force2to3):
+    """
+    Return a dictionary of extra args to pass to setup().
+
+    """
+    extra = {}
+    if py_version >= (3, ) or should_force2to3:
+        # Causes 2to3 to be run during the build step.
+        extra['use_2to3'] = True
+
+    return extra
+
+
 def main(sys_argv):
 
     # TODO: use the logging module instead of printing.
     # TODO: include the following in a verbose mode.
     print("pystache: using: version %s of %s" % (repr(dist.__version__), repr(dist)))
 
+    should_force2to3 = parse_args(sys_argv)
+
     command = sys_argv[-1]
 
     if command == 'publish':
@@ -308,6 +331,7 @@ def main(sys_argv):
 
     long_description = read(DESCRIPTION_PATH)
     template_files = ['*.mustache', '*.txt']
+    extra_args = get_extra_args(should_force2to3)
 
     setup(name='pystache',
           version=VERSION,
@@ -334,7 +358,7 @@ def main(sys_argv):
             ],
           },
           classifiers = CLASSIFIERS,
-          **extra
+          **extra_args
     )