Lennart Regebro  committed c2df24b

More docs for python 3 support.

  • Participants
  • Parent commits 955e8c4
  • Branches 0.6-maintenance

Comments (0)

Files changed (3)

File docs/index.txt

+   python3
 Indices and tables

File docs/python3.txt

+Supporting both Python 2 and Python 3 with Distribute
+Starting with version 0.6.2, Distribute supports Python 3. Installing and
+using distribute for Python 3 code works exactly the same as for Python 2
+code, but Distribute also helps you to support Python 2 and Python 3 from
+the same source code by letting you run 2to3 on the code as a part of the
+build process. by setting the keyword parameter ``run_2to3`` to True.
+Distrubute as help during porting
+Distribute can make the porting process much easier by automatically running
+2to3 as a part of the test running. To do this you need to configure the so that you can run the unit tests with ``python test``.
+See :ref:`test` for more information on this.
+Once you have the tests running under Python 2, you can add the run_2to3
+keyword parameters to setup(), and start running the tests under Python 3.
+The test command will now first run the build command during which the code
+will be converted with 2to3, and the tests will then be run from the build
+directory, as opposed from the source directory as is normally done.
+Distribute will convert all Python files, and also all doctests in Python
+files. However, if you have doctests located in separate text files, these
+will not automatically be converted. By adding them to the 
+``convert_doctests_2to3`` keyword parameter Distrubute will convert them as 
+By default, the conversion uses all fixers in the ``lib2to3.fixers`` package.
+To use additional fixes, the parameter ``additional_2to3_fixers`` can be set
+to a list of names of packages containing fixers.
+A typical can look something like this::
+      from setuptools import setup
+      setup(name='your.module',
+            version = '1.0',
+            description='This is your awesome module',
+            author='You',
+            author_email='your@email',
+            package_dir = {'': 'src'},
+            packages = ['your', 'you.module'],
+            test_suite = 'your.module.tests',
+            run_2to3 = True,
+            convert_doctests_2to3 = ['src/your/module/README.txt'],
+            additional_2to3_fixers = ['your.fixers']
+            )
+Differential conversion
+Note that a file will only be copied and converted during the build process
+if the source file has been changed. If you add a file to the doctests
+that should be converted, it will not be converted the next time you run
+the tests, since it hasn't been modified. You need to remove it from the 
+build directory. Also if you run the build, install or test commands before
+adding the run_2to3 parameter, you will have to remove the build directory
+before you run the test command, as the files otherwise will seem updated, 
+and no conversion will happen.
+In general, if code doesn't seem to be converted, deleting the build directory
+and trying again is a good saferguard against the build directory getting
+"out of sync" with teh source directory.
+Distributing Python 3 modules
+You can distribute your modules with Python 3 support in different ways. A
+normal source distribution will work, but can be slow in installing, as the
+2to3 process will be run during the install. But you can also distribute
+the module in binary format, such as a binary egg. That egg will contain the
+already converted code, and hence no 2to3 conversion is needed during install.
+Advanced features
+If certain fixers are to be suppressed, this again can be overridden with the
+list ``setuptools.commands.build_py.build_py.fixers``, which then contains the
+list of all fixer class names.
+If you don't want to run the 2to3 conversion on the doctests in Python files,
+you can turn that off by setting ``setuptools.run_2to3_on_doctests = False``.
+Note on compatibility with setuptools
+Setuptools do not know about the new keyword parameters to support Python 3.
+As a result it will warn about the unknown keyword parameters if you use
+setuptools instead of Distribute under Python 2. This is not an error, and
+install process will continue as normal, but if you want to get rid of that
+error this is easy. Simply conditionally add the new parameters into an extra 
+dict and pass that dict into setup()::
+      from setuptools import setup
+      import sys
+      extra = {}
+      if sys.version_info >= (3,):
+          extra['run_2to3'] = True
+          extra['convert_doctests_2to3'] = ['src/your/module/README.txt']
+          extra['additional_2to3_fixers'] = ['your.fixers']
+      setup(name='your.module',
+            version = '1.0',
+            description='This is your awesome module',
+            author='You',
+            author_email='your@email',
+            package_dir = {'': 'src'},
+            packages = ['your', 'you.module'],
+            test_suite = 'your.module.tests',
+            **extra
+            )
+This way the parameters will only be used under Python 3, where you have to
+use Distribute.

File docs/setuptools.txt

     mess with it.  For more details on how this argument works, see the section
     below on `Automatic Resource Extraction`_.
+    Convert the source code from Python 2 to Python 3 with 2to3 during the 
+    build process. 
-    List of doctest source files that need to be converted with 2to3. See
-    `Converting with 2to3`_ below for more details.
+    List of doctest source files that need to be converted with 2to3. 
+    See :doc:`python3` for more details.
+    A list of modules to serach for additional fixers to be used during
+    the 2to3 conversion. See :doc:`python3` for more details.
 Using ``find_packages()``
 remember to modify your setup script whenever your project grows additional
 top-level packages or subpackages.
-Converting with 2to3
-When run under Python 3.x, setuptools will automatically run 2to3 on
-all Python source files, if ``setuptools.run_2to3`` is set to True; by
-default, this variable is False. It will also convert doctests inside
-all Python source files, unless ``setuptools.run_2to3_on_doctests`` is
-False; by default, this setting is True. If additional files
-containing doctests need to be converted, the
-``convert_doctests_2to3``setup option should provide a list of all
-such files.
-By default, this conversion uses all fixers in the ``lib2to3.fixes``
-package. To use additional fixes, the list
-``setuptools.lib2to3_fixer_packages`` must be extended with names
-of packages containing fixes. If certain fixes are to be suppressed,
-this again can be overridden with the list 
-``setuptools.commands.build_py.build_py.fixers``, which then contains
-the list of all fixer class names.
 Automatic Script Creation