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