librsync now comes with a simple Python interface.  The point of this
is mostly to let proxy servers be prototyped in a scripting language,
while keeping the core algorithms in C so that they're fast and we
don't have to recreate them.

The main thing we want to wrap is the functions declared in
librsync.h: they generate signatures, encode, and decode, and in each
case take callback functions that do the actual I/O.  rproxy.c uses
this to either handle files or base64 encoded memory buffers.  In the
future we will also use it to handle Apache BUFF* streams, and in
Apache 2.0 it will handle IOL structures.

In Python, we just pass callable objects which either take or return
strings.  Python strings can contain nuls, but we have to be careful
to handle them as memory regions in C, not as strzs.  These could
either be functions with some default arguments, or (more likely)
bound methods.

So, for example

    from StringIO import StringIO

    to_sign = StingIO('some data to sign')
    sig = StringIO()
    block_size = 4

    rsync.signature(to_sign.read, sig.write, block_size);

    sig_val = sig.getvalue()

It seems better to let the client and StringIO class worry about
converting from strings into the more general read/write method
interface. 

The 'original' stream into rsync.decode has to be handled specially,
because it must be seekable.  Therefore we expect it to be a callable
that takes two parameters, being offset and length.  In general this
is going to be a seek and then a read.  There is no single function in
any standard Python interfaces, so people might have to write a bit of
glue themselves.


>> Using the interface

The rsyncmodule.so file must be in your PYTHONPATH: Python doesn't
look in the LD_LIBRARY_PATH.  You can't run it from a directory which
contains libtool's rsyncmodule.so wrapper, unless you munge sys.path
after starting up: '' is prepended to PYTHONPATH.