Wrapping up the summer

Unfortunately, I have been unable to completed the entire project.  Here's where things stand right now:  There are enough of the ETG (tweaker) scripts converted in order for the main module to be imported and for a number of the simple demos to run.  That said, a bunch of functionality is missing from the main module and none of the submodules (wx.html, wx.grid, etc.) work.  Converting the remainder of the ETG scripts is something that is just going to take more time.  Many of them are simple enough, but some of them have a lot of additions that use the C-API and will require a significant amount of time and work.

I've spent the last couple of days working on some documentation.  I've decided to focus on writing documentation for converting etg scripts rather than for the internals of the generator.  Although there are doubtlessly bugs in the generator yet to be fixed (I already know of at least a couple), I think most of the work that needs to be done and that is likely to be done by someone else is working with the ETG scripts.

I don't plan on abandoning this project. I want see this project through to its completion. I've asked permission to continue working on this project as a part of a class this semester.  I haven't gotten a response just yet, but I'm hopeful.

Sip annotations

I've finally, finished implementing all of the sip annotations that are currently used by wxPython Phoenix.  Barring some unexpected requirement (and doubtless there will be at least one) the generator itself should be complete.

To talk about sip annotations a bit: sip uses what it calls annotations, specified by extra code added to .sip files, to allow the default before of the generated bindings to be changed.  Annotations can applied to basically any C++ definition.  The ones that are relevant here are annotations for classes, methods, method parameters, and variables. 

An example of what an annotated function definition would look like in a .sip file (taken sip's documentation):

void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/;

Since the existing wxPython code is pretty heavily tailored to sip, the tweaker scripts reference these annotations directly.  This also makes sense, I suppose, since there isn't really a good, predefined way to specify the various behaviors of the annotations represent.  The problem, however, was that some of the annotations are poorly documented.

The worst example of an annotation being poorly documented is the Transfer annotation.  When applied to a function,Transfer indicates that the ownership of the return value is given to C++.  That much is pretty clear from the documentation anyway.  What is not documented is that when Transfer is applied to a Ctor, sip increments the refcount for the new object an extra time.  The effect of this is that the (Python) object will not be garbage collected until either its (hopefully virtual) C++ Dtor is called or the ownership of the object is somehow changed.

For a more mild example, I don't know how many times I read the documentation for the KeepReference code before I figured out how its 'keys' work. (And only after I implemented that functionality did I realize that wxPython never specifies the key to use...)


Moving forward, I now need to modify the tweaker scripts to make them compatible with the new generator.  My plan for this is to remove all of the scripts, and add them back one by one.  As I add them back, I plan on splitting any sip-specific and cffi-specific code into separate files which can be imported by the shared script depending on the generator being used.

To be perfectly honest, I don't expect to finish modifying all of the scripts before the 16th.  For now, I've settled on trying to have most of the core module working by then.  I wanted to be at this point about a month ago, but things always seem to take me longer than I plan for them too.