Merge branch 'issue-121-2to3-documentation' into 'development'

This addresses issue #121:

  https://github.com/defunkt/pystache/pull/121

HISTORY.md

@@ -9,6 +9,7 @@ History
 -   Added a `parse()` function that yields a printable, pre-compiled
     parse tree.
 -   Added support for rendering pre-compiled templates.
+-   Added --force2to3 option to setup.py (issue \#121).
 -   Bugfix: exceptions raised from a property are no longer swallowed
     when getting a key from a context stack (issue \#110).
 -   Bugfix: lambda section values can now return non-ascii, non-unicode

README.md

@@ -40,6 +40,12 @@ Pystache is tested with--
 -   Python 3.1
 -   Python 3.2
 
+[Distribute](http://packages.python.org/distribute/) (the setuptools fork)
+is recommended over [setuptools](http://pypi.python.org/pypi/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
@@ -56,6 +62,9 @@ Install It
 ----------
 
     pip install pystache
+
+And test it--
+
     pystache-test
 
 To install and test from source (e.g. from GitHub), see the Develop
@@ -122,8 +131,8 @@ Pystache has supported Python 3 since version 0.5.1. Pystache behaves
 slightly differently between Python 2 and 3, as follows:
 
 -   In Python 2, the default html-escape function `cgi.escape()` does
-    not escape single quotes; whereas in Python 3, the default escape
-    function `html.escape()` does escape single quotes.
+    not escape single quotes.  In Python 3, the default escape function
+    `html.escape()` does escape single quotes.
 -   In both Python 2 and 3, the string and file encodings default to
     `sys.getdefaultencoding()`. However, this function can return
     different values under Python 2 and 3, even when run from the same
@@ -202,18 +211,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
+using it with Python 3.  The installation process (and tox) do this
 automatically.
 
+To convert the code to Python 3 manually (while using Python 3)--
+
+    python setup.py build
+
+And while using Python 2--
+
+    python setup.py --force2to3 build
+
+Both of the above write the converted code to a subdirectory called `build`.
+
+To convert the code without using setup.py, you can use
+[2to3](http://docs.python.org/library/2to3.html) as follows (two steps)--
+
+    2to3 --write --nobackups --no-diffs --doctests_only pystache
+    2to3 --write --nobackups --no-diffs pystache
+
+This converts the code (and doctests) 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 of the code (e.g. from the `build` directory after converting),
+and not from the original (unconverted) source directory.  Otherwise, you will
+get a syntax error.  You can help prevent this by not running the Python
+IDE from the project directory when importing Pystache while using Python 3.
+
 
 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
     )