Wednesday, September 11, 2013

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.

No comments:

Post a Comment