[PATCH]: Python bindings

[Mark Jenkins]

Hello again GnuCash developers,

Attached is a patch that adds python binding support.

I've been working on this recently with my colleague Jeff Green, your
2007 Google SoC register-rewrite student. We're both members/employees
of ParIT Worker Co-operative, (http://parit.ca) in Winnipeg, Canada.
Just to let you know, Jeff's work on the register-rewrite over the last
few months has been paid for by ParIT, as is my python binding work.

I last talked about python bindings almost a year ago:
http://lists.gnucash.org/pipermail/gnucash-user/2007-March/019720.html

Derek replied:
> Any reason not to feed these back to us for trunk?

I had reasons, but none of them were any good, and I agreed with the idea:
> If having this be part of GnuCash is consistent with the project's
> goals, I'd be glad to put in the work needed to merge it in.

In fact, there turned out to be many reasons why a separate project was
a bad idea:

* I was using private (not exported to $prefix/include/gnucash) headers,
which required people to download the GnuCash source to build the
bindings. Ouch.

* There was limited pressure on me to keep the bindings in sync with
changes in GnuCash's api. (if these made it here upstream and later got
pulled out from bit-rot, my employer would be very unhappy with me)

* More effort is involved to keep the two apis in sync, two projects and
two source trees to build and work with instead of one.

* Less leverage of the GnuCash community


I've tried to keep this patch minimal, just enough to open/create and
save a file, e.g. all the qof_session_* functions. My original bindings
were bigger, they included support for most of the engine and business
stuff. This initial minimalism should make the patch easier for you to
judge.

The attached patch is also small because I'm re-writing these python
bindings. There were many things about the old ones that made
maintenance not as easy as I would of liked. I figured it was better to
submit here right away before that re-write was completed, to allow this
community to participate from the beginning.

I think the new binding architecture is nice, and your feedback will be
appreciated.

GnuCash's headers are swig safe (Thank you!), and we can get away with
our swig interface file simply containing:

%include <qofsession.h>

instead of having to list each piece of the api one by one to avoid swig
errors.

For each set of C api functions that act as a class, we create a python
class and add most of the C api functions with pattern matching like so:

"""
class Session(ClassFromFunctions):
    _module = gnucash_core_c
    _new_instance = "qof_session_new"

Session.add_methods_with_prefix("qof_session_")
"""

So with that, you get qof_session_save as Session.save,
qof_session_begin as Session.begin, and all the without having to list them.

So, you do such a good job of naming your functions in the same class on
a consistent basis, that this gets us a huge part of the api for free,
again without having to list it. (Thank you again)

Further refinements to these functions can be added with decorators. For
example, I wanted calls to qof_session_load and qof_session_save to have
None as a default argument for the progress bar (so you can just call
Session.save() and not monitor progress) - so I created and added a
decorator for it:

def one_arg_default_none(function):
    return default_arguments_decorator(function, None, None)

Session.decorate_functions(one_arg_default_none, "load", "save")


To enable the bindings, you have to use --enable-python-bindings.

I would be willing and honoured to further develop these here upstream
in a branch, but given that the python bindings are completely optional
(and off by default) perhaps you would even find it reasonable to put
these in trunk from the start, even before they reach completion and
maturity?

Additional information in
src/optional/python-bindings/README


Mark Jenkins,
ParIT Worker Co-operative

p.s.

README.patches says I should use diff -urN instead of svn diff when
submitting patches that add new files. (like this one). Because I added
my new files with svn add, (and tested the resulting patch against a
blank trunk), the patch I generated via svn diff seems to be fine. I
understand that after applying it you'll have to svn add the new files,
but is this any different with a diff generated patch?


bcc some people who have expressed interest in this
-------------- next part --------------
A non-text attachment was scrubbed...
Name: python-bindings.patch
Type: text/x-patch
Size: 23966 bytes
Desc: not available
Url : http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20080227/bc423b48/attachment.bin