Project Phoenix Library Migration
This page is for information about the issues, suggestions, requirements, and procedures for migrating the Classic version of the wx.lib, wx.py, and wx.tools Python packages to the new Phoenix version of wxPython.
High Level Requirements
- There is NO intention to try and share library code between the Classic and Phoenix versions of wxPython.
There however does need to be support for both Python 2.7 and Python 3.2+, preferably by having modules that are written to be compatible with both Python flavors. Otherwise so some type of code sharing between Python flavors will be desirable. (See some spitball ideas at ProjectPhoenix/Python2to3Issues.)
- The maintenance burden for the developers and contributors should be as low as possible.
- The complexity and confusion factors for the library users should be low.
Migration Plan
Phase 1
Do some svn copy and etc. commands to branch wxPython's wx.lib into Phoenix's wx.lib package.
This will not include wx.tools.XRCed and wx.tools.Editra, because I think it was a mistake to include these in the wx package namespace. (I still want to include them in distributions, but packaged differently so their code is independent instead of part of the rest of the wx Python package.)
I think that the branch should include the wx.lib sub-packages which are currently tracked in https://svn.wxwidgets.org/svn/wx/wxPython/3rdParty/. So this will end up being a branch for them as well, and will also get rid of the need to use svn:externals to blend things together into one work space because svn:externals makes it very difficult to use git or hg to make mirrors of the repository or use them as a front-end to svn.
Phase 1 is complete.
Phase 2
The goal of this phase is to migrate the existing wx.lib code to the API provided by Phoenix for Python 2.7. This will be a great place for community members to jump in and help out, whether they have commit access or not.
For each of the modules in wx.lib and its sub-packages do the following:
- Determine if the module should be kept or tossed out. This may sound harsh but I expect that there are some modules that are seldom used and/or may not even be fully compatible with Classic. If it's dead weight let's get rid of it. If in doubt, discuss on wxPython-dev.
- Add or update the docstrings in the module to be compatibile with Sphinx's flavor of restructured text. Every module should have a docstring as well as every function, class or method that is intended to be used by the developer who using the module.
Write a unittest module for the module being migrated. Every module should have a corresponding unittest module unless the module contains only abstract classes that can not be used by themselves. The unittest should at least ensure that the library module can be imported, that any styles, flags or event classes exist, that instances of the widget classes can be created, and if there is anything tricky, questionable, or fragile implemented by the library module then that thing should be exercised and tested that it works as it is supposed to. The unittest modules should be placed in the Phoenix/unittests folder with names like test_lib_modulename.py for items in wx.lib or test_lib_subpackage_modulename.py for modules in subpackages of wx.lib.
If using the module or sub-package is complex and/or you feel like the unittest does not do it justice, then also add one or more small standalone sample applications under Phoenix/samples/lib or Phoenix/samples/lib/subpackage as appropriate. Use a sub-folder name that matches the module name.
- Wash-Rinse-Repeat until there there is good unittest coverage of everything in the module that should be tested, and all tests pass. If possible test on more than one platform
Add a Tags: line in the module's header that indicates what has been done to the module so far. More tags can be added as needed, but those currently used are:
phoenix-port: The module has been updated to be compatible with the Phoenix API.
unittest: A unittest module has been created for the library module.
documented': The docstrings in the module have been updated to follow the standards given at ProjectPhoenix/DocumentationProject
py3-port: The library module and the unittest module have been updated to be compatible with both Python 3 and Python 2 and all tests pass.
approved: The migration of the library module has been approved by the BDFL.
- Either commit your changes to subversion if you have commit access and close the ticket, or upload a patch to the Trac ticket for the module.
While migrating the code in this phase if there are easy things you notice along the way that will help with Python3 compatibility then go ahead and change them now. For example, changing print statements to look like print function calls by enclosing the expression in parentheses, or changing relative imports to absolute imports, etc. Feel free to add appropriate from __future__ import ... statements when needed to make it work.
Phase 3
The final phase of the migration is making the library code compatible with both Python 2.7 and Python 3.2+. (See ProjectPhoenix/Python2to3Issues for some issues and ideas that were discussed several weeks ago.) From my experience with porting the various build scripts to be usable from both Pythons I found that with some care that there are many things which can be made to be compatible simply by doing things a little differently in the Python 2.7 version, possibly due to adding a __future__ import to change 2.7's behavior a little. Almost everything else could be handled by adding some helper functions that contained some conditional code that checked the version of Python being used and implemented the feature accordingly in each case.
There is a 3rd-party project called six (documentation) which has a lot of these types of helpers already worked out for us, and I've dropped a copy of it in to wx.lib for us to use. Please utilize it for making things compatible with both Py2 and Py3 as much as possible. If you feel the need to add something to wx.lib.six then go ahead, just mark your additions with a comment starting with #*# so we can easily keep track of them.
The final decision for the approach to take for Phase 3 and more detailed instructions will be made when we get closer to it.