futurize quick-start guide¶
How to convert Py2 code to Py2/3 code using
Step 0: setup¶
Step 0 goal: set up and see the tests passing on Python 2 and failing on Python 3.
Clone the package from github/bitbucket. Optionally rename your repo to
Create and activate a Python 2 conda environment or virtualenv. Install the package with
python setup.py installand run its test suite on Py2.7 (e.g.
python setup.py testor
Optionally: if there is a
.travis.ymlfile, add Python version 3.6 and remove any versions < 2.6.
Install Python 3 with e.g.
sudo apt-get install python3. On other platforms, an easy way is to use Miniconda. Then e.g.:
conda create -n py36 python=3.6 pip
Step 1: modern Py2 code¶
The goal for this step is to modernize the Python 2 code without introducing any dependencies (on
future or e.g.
six) at this stage.
future into the virtualenv using:
pip install future
futurize --stage1 -w *.py subdir1/*.py subdir2/*.py. Note that with
recursive globbing in
zsh, you can apply stage 1 to all source files
futurize --stage1 -w .
1c. Commit all changes
1d. Re-run the test suite on Py2 and fix any errors.
See Stage 1: “safe” fixes for more info.
One relatively common error after conversion is:
Traceback (most recent call last): ... File "/home/user/Install/BleedingEdge/reportlab/tests/test_encrypt.py", line 19, in <module> from .test_pdfencryption import parsedoc ValueError: Attempted relative import in non-package
If you get this error, try adding an empty
__init__.py file in the package
directory. (In this example, in the tests/ directory.) If this doesn’t help,
and if this message appears for all tests, they must be invoked differently
(from the cmd line or e.g.
setup.py). The way to run a module inside a
package on Python 3, or on Python 2 with
absolute_import in effect, is:
python -m tests.test_platypus_xref
(For more info, see PEP 328 and the PEP 8 section on absolute imports.)
Step 2: working Py3 code that still supports Py2¶
The goal for this step is to get the tests passing first on Py3 and then on Py2
again with the help of the
futurize --stage2 myfolder1/*.py myfolder2/*.py
You can view the stage 2 changes to all Python source files recursively with:
futurize --stage2 .
To apply the changes, add the
This stage makes further conversions needed to support both Python 2 and 3.
These will likely require imports from
future on Py2 (and sometimes on Py3),
from future import standard_library standard_library.install_aliases() # ... from builtins import bytes from builtins import open from future.utils import with_metaclass
Optionally, you can use the
--unicode-literals flag to add this import to
the top of each module:
from __future__ import unicode_literals
All strings in the module would then be unicode on Py2 (as on Py3) unless
explicitly marked with a
If you would like
futurize to import all the changed builtins to have their
Python 3 semantics on Python 2, invoke it like this:
futurize --stage2 --all-imports myfolder/*.py
2b. Re-run your tests on Py3 now. Make changes until your tests pass on Python 3.
2c. Commit your changes! :)
2d. Now run your tests on Python 2 and notice the errors. Add wrappers from
future to re-enable Python 2 compatibility. See the
Cheat Sheet: Writing Python 2-3 compatible code cheat sheet and What else you need to know for more info.
After each change, re-run the tests on Py3 and Py2 to ensure they pass on both.
2e. You’re done! Celebrate! Push your code and announce to the world! Hashtags #python3 #python-future.