[PyKDE] PyKDE and libkdegames

[Jim Bublitz]

On 10-Jun-02 Neil Stevens wrote:
> Could anyone give me any advice on how to make a wrapper for
> libkdegames (or any of the other extra libs for that matter) in
> the way PyKDE wraps kdelibs?
 
> My first obvious steps would be to look on a cvs or the sip docs,
> but lacking both I hope for some help here. :-)

Basically, there are only a few simple rules for generating sip
description files (.sip) from C++ headers:

1. Delete any forward declarations
2. Change 'class someClass : public QWidget' to 
'class someClass : QWidget'
3. Add %HeaderCode block to include C++ .h file
4. Delete all argument variable names (but not default values).
5. Delete all protected variables, anything private EXCEPT
ctors/dtors. Delete public dtors. ALL pure virtual methods must
be included, even if private.
6. Any methods which pass int&, int*, bool&, bool* etc. (basic
types, not objects) or char ** will require handwrittten code
(%MemberCode). Same if you want to pass/return Python data
structures (lists, tuples, etc)
7. Anything template based (eg QList <QString>) will require either
handwritten code or a %MappedType.
8. Eliminate duplicate typedefs if any
9. Namespaces need some special handling, mostly in naming objects 
in namespaces - see KParts stuff
10. There are some minor syntax adjustments needed - for example
'unsigned short int' probably won't parse, but 'ushort' will.

You can find the sip syntax/switches and gcc switches in the
Makefiles; the *.sip-in files drive the code generation process and
also provide the ability to have sip construct Makefile.am files
for you. The *.sip-in files are converted to *.sip files via some
stuff in the Makefiles. In PyKDE, they're now in
PyKDE-3.2.4/sip/kde*

dcop in PyKDE or qttable in PyQt are fairly simple examples you can
look at - start with dcop.sip-in for example and then compare the
%Included files from that to the KDE h files. There are some
potential stumbling blocks, but you can usually get a fairly quick
response from this list. Boudewijn Rempt's book has a short appendix
with an example of converting h files to sip files.

The other thing to consider is whether you want Python bindings for
the entire lib or want to write a C++ wrapper and do Python
bindings for that.

If you do bindings for the entire lib, sip needs full dependency
info for all objects you reference. For example, kdecore requires
dcop bindings, kdeui requires kdecore and dcop, etc. (see %Import
statements in PyKDE). The advantage of a full set of bindings is
that they are completely general and anything can be subclassed.
The disadvantage is that you need a lot of sip files and the
libraries generated can be large. PyQt and PyKDE are done this way.

On the other hand, you can write a simple C++ wrapper in some cases
that only exposes those parts of the API that you need in Python,
and then write Python bindings for the C++ wrapper. The advantages
are that you need to do a lot less work for sip, you can make the
API more "rational" for Python programmers, the resulting libs
are a lot smaller, and you can design the wrapper to be easily
implemented via sip. The disadvantages are the loss of flexibility
and loss of ability to subclass as generally. I don't know of
anything released this way yet, but have done some stuff for
plugins this way.

The other thing to consider is code steal^H^H^H^H^Hsharing. I don't
know what you plan to do with this, but I'd certainly look at
things like PySol and see what's already available in Python for
your application. KDE/Qt does a lot of stuff (for example, sockets,
DOM) that's already implemented nicely in Python.

Last, if you have a very large project (say 20 or more h files) and
are not in a big hurry, let me know and I'll see if I can generate
the sip files for you. I have some semi-automated tools to do it,
but they only generate about 80% - 90% clean code and require a lot
of manual touch-up. I'm also pretty backed up with work at the
moment, but if it's pretty straightforward KDE stuff (full bindings)
I might be able to get to it fairly soon.

Jim