Home | History | Annotate | Download | only in docs 
      1 =====================================================
      2 Supporting both Python 2 and Python 3 with Setuptools
      3 =====================================================
      4 
      5 Starting with Distribute version 0.6.2 and Setuptools 0.7, the Setuptools
      6 project supported Python 3. Installing and
      7 using setuptools for Python 3 code works exactly the same as for Python 2
      8 code.
      9 
     10 Setuptools provides a facility to invoke 2to3 on the code as a part of the
     11 build process, by setting the keyword parameter ``use_2to3`` to True, but
     12 the Setuptools strongly recommends instead developing a unified codebase
     13 using `six <https://pypi.org/project/six/>`_,
     14 `future <https://pypi.org/project/future/>`_, or another compatibility
     15 library.
     16 
     17 
     18 Using 2to3
     19 ==========
     20 
     21 Setuptools attempts to make the porting process easier by automatically
     22 running
     23 2to3 as a part of running tests. To do so, you need to configure the
     24 setup.py so that you can run the unit tests with ``python setup.py test``.
     25 
     26 See :ref:`test` for more information on this.
     27 
     28 Once you have the tests running under Python 2, you can add the use_2to3
     29 keyword parameters to setup(), and start running the tests under Python 3.
     30 The test command will now first run the build command during which the code
     31 will be converted with 2to3, and the tests will then be run from the build
     32 directory, as opposed from the source directory as is normally done.
     33 
     34 Setuptools will convert all Python files, and also all doctests in Python
     35 files. However, if you have doctests located in separate text files, these
     36 will not automatically be converted. By adding them to the
     37 ``convert_2to3_doctests`` keyword parameter Setuptools will convert them as
     38 well.
     39 
     40 By default, the conversion uses all fixers in the ``lib2to3.fixers`` package.
     41 To use additional fixers, the parameter ``use_2to3_fixers`` can be set
     42 to a list of names of packages containing fixers. To exclude fixers, the
     43 parameter ``use_2to3_exclude_fixers`` can be set to fixer names to be
     44 skipped.
     45 
     46 An example setup.py might look something like this::
     47 
     48     from setuptools import setup
     49 
     50     setup(
     51         name='your.module',
     52         version='1.0',
     53         description='This is your awesome module',
     54         author='You',
     55         author_email='your@email',
     56         package_dir={'': 'src'},
     57         packages=['your', 'you.module'],
     58         test_suite='your.module.tests',
     59         use_2to3=True,
     60         convert_2to3_doctests=['src/your/module/README.txt'],
     61         use_2to3_fixers=['your.fixers'],
     62         use_2to3_exclude_fixers=['lib2to3.fixes.fix_import'],
     63     )
     64 
     65 Differential conversion
     66 -----------------------
     67 
     68 Note that a file will only be copied and converted during the build process
     69 if the source file has been changed. If you add a file to the doctests
     70 that should be converted, it will not be converted the next time you run
     71 the tests, since it hasn't been modified. You need to remove it from the
     72 build directory. Also if you run the build, install or test commands before
     73 adding the use_2to3 parameter, you will have to remove the build directory
     74 before you run the test command, as the files otherwise will seem updated,
     75 and no conversion will happen.
     76 
     77 In general, if code doesn't seem to be converted, deleting the build directory
     78 and trying again is a good safeguard against the build directory getting
     79 "out of sync" with the source directory.
     80 
     81 Distributing Python 3 modules
     82 =============================
     83 
     84 You can distribute your modules with Python 3 support in different ways. A
     85 normal source distribution will work, but can be slow in installing, as the
     86 2to3 process will be run during the install. But you can also distribute
     87 the module in binary format, such as a binary egg. That egg will contain the
     88 already converted code, and hence no 2to3 conversion is needed during install.
     89 
     90 Advanced features
     91 =================
     92 
     93 If you don't want to run the 2to3 conversion on the doctests in Python files,
     94 you can turn that off by setting ``setuptools.use_2to3_on_doctests = False``.
     95