[PyKDE] SIP questions

[Jim Bublitz]

On 25-Mar-03 Phil Thompson wrote:
> On Tuesday 25 March 2003 7:20 pm, WELCH,DONALD J
> (HP-Vancouver,ex1) wrote:
>> Greetings-

>> I am attempting to wrap a shared library on Linux using SIP.
>> This shared
>> library's API defines several C++ classes that interelate (in
>> both IS-A and
>> HAS-A relationships). Currently, all the classes are declared in
>> a single
>> .h file.

>> Questions:

>> 1. What is the difference between %Import and %Include?
 
> %Import is used when you are wrapping a library that sub-classes
> from another library that has also been wrapped. So PyKDE
> effectively %Imports PyQt.

> %Include is similar to the C pre-processor's #include.

Ignoring the fact that Phil wrote sip and I'm just a user, I think
%Import is closer to a C++ #include - %Import is like all of the
#includes you add *except* the one that has the same name as your
cpp file. It provides all of the external refs. %Include is more
like the list of source files in the Makefile - the %Includes are
the files that comprise the module and the ones code will be
generated for. 
 
> Whether you put each class into a separate .sip file is a
> readability issue and is up to you.

sip still generates one cpp/h file pair per class, but how you
distribute classes over sip files makes no difference to anything.
Every class needs a %HeaderCode block though, no matter how you
arrange things.
 
> SIP is run against the qtmod.sip file (not against each
> individual .sip file) and it brings in all the necessary stuff
> through %Includes.

In that sense sip is more like a linker than a compiler, in that it
reads in all of the sip files for a module before resolving
symbols. Ignoring scope, any symbol in any sip file is visible to
all other sip files, and in fact sip won't tolerate multiple
declarations (eg duplicate typedefs).
 
>> 6. Is it possible to add methods to classes in the .sip file
>> that don't exist in (or exist differently) the wrapped .cpp
>> code? For example, could I add a method that returns a Python
>> list instead of having the Python client code call
>> getFirst()/getNext() to enumerate a list of items?
 
> Yes - you can lie to SIP as much as you want.
 
> Depending on the nature of the class, alternatives would be to
> replace the class entirely with a Python list (using
> %MappedType), or implement appropriate Python operators (see
> qstringlist.sip).

There are a lot of examples in PyKDE - grep the sip files for
%MemberCode, %MappedType, %C++Code, or %PrePythonCode.
qstringlist.sip is a neat example of handling a template based
class (by ignoring the base class) and adding Python __methods__
(same as KURL::List, for which I stole the code from QStringList).
KCmdLineArgs has an example of replacing an array of C++ structs
with a Python dict.
 
>> 7. Are there any tools to automate h2sip (at least the basic
>> stuff that can be automated)?
 
> Over to you Jim.

I have an automated tool that does PyKDE automatically almost
perfectly (about a half dozen known errors in 400+ files) except for
handwritten code (it did some of that too, but not very well). It
also does versioning, writes the docs (minimally at the moment, but
I've been thinking of hacking the KDoc stuff too, similar to what
theKompany just announced for PyQt), and constructs the build.py
file that generates the make files. I sent it to someone last week
and quickly realized it's pretty difficult for anyone else to make
sense of at the moment, and is also pretty PyKDE specific. That's
given me second thoughts about releasing it, but assuming I still
do release it, it won't be for 3-6 months. The core parser/sip
file generator is pretty good (a few bugs and a lousy
C preprocessor parser) but the input file specification is pretty
horrible and the build files generated won't work except for PyKDE
(but are hackable).

I will, however, send you a copy if you want to give it a try. Just
don't expect much. It's Python, so it only takes a few minutes to
decide if it's worth your effort or not. Let me know.
 
> However, be aware that you sometimes have to supply SIP with more
> information  (eg. /Transfer/ flags) which cannot be done
> automatically.

I do those automatically :) - also the SIP_RXOBJ_CON and
SIP_SLOT_CON stuff except for the args if needed - I generate them
all commented out and then add the args to SIP_SLOT_[CON,DIS]
manually. Depends on the consistency of the C++ code though - I
just assign every QWidget *parent in a ctor /TransferThis/ and
every other case a /Transfer/, and then go back a remove a few
manually. Those are almost the only necessary info that's not in the
h files (and stuff that needs %MemberCode or %MappedType, which I
flag automatically).


Jim