documentation for python bindings

[Mark Jenkins]

> Looking through the
> source code and the provided examples, it looks like the API can be used
> both for reading and writing.  No help available anywhere on how to
> actually use that stuff?

Documentation is pretty bad right now. Help needed.

The examples you refer to are found in
gnucash/trunk/src/optional/python-bindings/example_scripts
gnucash/trunk/src/optional/python-bindings/tests

Best source of documentation at the moment the gnucash C api headers. If
you look at the .i files, you'll see which headers are covered.

For every header included in a .i file, you'll find that the constants
and functions from each included header are available unless explicitly
excluded.

You can see the big long list of stuff via
>>> import gnucash.gnucash_core_c
>>> help(gnucash_core_c)
>>> dir(gnucash_core_c)


But, more often than not you'll hope to find what you need in
>>> import gnucash.gnucash_core
>>> import gnucash.gnucash_business
>>> help(gnucash.gnucash_core)
>>> help(gnucash.gnucash_business)

The modules gnucash_core and gnucash_business provide a higher level of
abstraction. They define python classes that match the GnuCash data
types and use basic pattern matching on the function names found in
gnucash_core_c to wrap those functions into class instance methods.

So, instead of
void xaccAccountSetName (Account *account, const char *name);
(from Account.h)

You can do
a = Account(...)
a.SetName("Money")

For methods like the above, the first argument is automatically
supplied. If we doing this at the lower level, things would look like this:

a = Account(...)
xaccAccountSetName( a.get_instance(), "Money")

Note that the get_instance() method provides an object that co-responds
the underlying C pointer. The high level classes in gnucash_core.py and
gnucash_business.py automatically call it on any arguments to underlying
C functions.

If you look at gnucash_core.py you'll see what patterns are being
searched for to add methods.

In addition, we identify functions where the return value can be wrapped
in a high level class, and do so.


Admittedly, more of this stuff could be done at the SWIG layer. SWIG has
a pretty nifty system for setting up type translations, and we could
probably reduce the code size and support more of the api this way. It
would be cool if we could even create python documentation strings from
the C documentation strings.

Ultimately, I'd like to make a patch to swig that let's me do c function
to OO class method mapping entirely in SWIG. Not likely any time soon
though.


There are also documentation strings in our old python bindings
http://www.parit.ca/software/pscproject.2008-04-22.3713003400/releases/0.7.61
Some of these are wrong for the new API, but some parts are fine and
could be copied over here.

There are also extra conveniences in the old bindings that I hope to
bring over eventually, esp being able to set important attributes of
objects in the constructor, instead of having to construct first and set
values after.


Mark