In this post we look at porting the coils library from Python 2.7 to Python 3.5.3 and having it on both versions. Coils is a data structure library that was coded in 2015. It has implementations of basic data structures like hash tables, binary search trees and splay trees, list and heaps. Coils code is available here. The steps described here are based on official documentation on porting here. It would be necessary to go through it before attempting to port your project.
The ported code can be installed from https://pypi.org/project/pycoils/
Lets see the steps for porting coils library:
1) Create 2 virtual environments, one for Python 2.7.15 and Python 3.5.3
2) pip install future on both environments.
3) Ensure that all tests pass in the Python 2.7.15 environment to begin porting.
You need tests and good coverage in your project. One way to be sure that the code would work as expected after porting to Python 3 and also on Python 2 is by ensuring that all tests pass on both versions. Here we see a screen of 255 tests for the project on both.
coils also had good test coverage as shown below.
If you do not have any tests on your project, there is no way to identify regressions introduced by porting. This is because porting involves not only using tools to refactor but also, manual changes to pass tests.
If your coverage is low, write or modify tests to increase it.
4) Run futurize --stage1 -w **/*.py
(When using globstar ** make sure that it is enabled)
This will modernize the code without introducing any dependencies. You will see a lot of output regarding the code that was refactored. This is shown below.
Once the run is complete without errors, you can use a diff tool to see what code was changed to support python 3 in stage 1. In this example we see python 3 style in operator brought in to replace has_key.
5) Commit the changes. Rerun tests on Python 2 environment and manually fix any errors to ensure tests pass.
6) Run futurize --stage2 -w **/*.py
The aim is to ensure that code works on both Python 3 and then back on Python 2 with future. As before the command will output the refactoring done.
The changes can be checked with a diff tool too. Here we see the support for the division method on Python 3 and Python 2 with future package.
7) Run the tests again on Python 3. Note that test cases may also have been ported to Python 3 and will need changes to run on both Python 3 and Python 2.
Here we see some manual fixes to the test cases. This was to a) Drop deprecated key-word arguments and b) Drop deprecated TestCase class method aliases.
8) Once the tests pass on both Python 2 and Python 3, then you have a stable version that can be used in both environments.
Coils library has an examples package which demonstrates how the library's data structures can be used in code. For example, creating a min heap, adding data and performing heap operations.
This is also used to ensure that things work as expected on both.
There are some post conversion steps (depends on your code). After that as tests and examples run on both versions, we have Coils for Python3/Python2.
