Yeah David, you've got some great description there. +1
- Dan
On Tue, 20 Mar 2007, C. Michael Pilato wrote:
> Dave, you think you could take the informational bits of this mail and stuff
> them into a nice fat TODO file in the bindings/swig/python directory, or
> some similar sane place?
>
>
> David James wrote:
> > Hi Edin,
> >
> > It's great to hear you're interested in helping out with the Python
> > bindings. I'd be happy to mentor any students who are interested in
> > this task.
> >
> > Currently, the Subversion Python bindings are implemented using SWIG
> > (see http://www.swig.org/). SWIG is an automatic wrapper generator
> > which generates bindings for several languages including Python.
> >
> > Inside SWIG "interface" files, we provide SWIG with typemaps which
> > explain how to convert between Python datatypes and Subversion native
> > datatypes.
> >
> > These datatype conversions include:
> > - apr_array_header_t <-> Python array
> > - apr_hash_t <-> Python dictionary
> > - svn_string_t <-> Python string
> > - svn_stringbuf_t <-> Python string
> > - svn_error_t * ==> (If an error occurs, throw a Python exception)
> >
> > If SWIG was perfect, our SWIG bindings could probably consist of five
> > short interface files, which explained how to convert those five
> > datatypes between Python and Subversion, and we would have basic, raw,
> > Python bindings, which look a lot like the original Subversion/C API,
> > but are written in Python.
> >
> > Let's pretend for a few moments that SWIG is perfect, and that we
> > already have perfect SWIG bindings for all of Subversion's datatypes.
> > (This is by no means true! But let's pretend for a moment.)
> >
> > Now that we have raw bindings to Subversion, your job is to create a
> > friendly object-oriented interface to Subversion which is more
> > Pythonic in nature.
> >
> > What would Pythonic bindings look like? Here's a few examples of what
> > you would be able to do with Python bindings:
> >
> > client = SubversionClient("http://svn.collab.net/repos/svn/trunk",
> > username="joecommitter", password="joepassword")
> >
> > # Print out the README
> > print client.cat("README")
> >
> > # Find out who wrote "line 1" of the README file
> > lines = client.blame("README")
> > print lines[0].author
> >
> > # Move a file
> > client.move("README", "README2", message="Move the readme file to a
> > less obvious location")
> >
> > # Do several operations in a single transaction
> > files = client.ls()
> > txn = client.transaction()
> >
> > # Make sure that every file in the "trunk" directory starts with a
> > "hip_" prefix.
> > for file in files:
> > txn.move(file, "hip_%s" % file)
> >
> > # Commit all of the changes at once
> > txn.commit(message="Make the Subversion trunk more hip!")
> >
> > # Checkout repositories to disk
> > wc = client.checkout()
> >
> > # Commit changes
> > open("hip_README2","w").write("Hello world\n")
> > wc.commit(message="Update the README2 file")
> >
> > Wouldn't it be great if the Python bindings were that easy to use?
> > Unfortunately, it's not that easy, but it should be. We need a summer
> > volunteer to fix this problem as a Summer of Code project.
> >
> > Unfortunately, there's a few obstacles (imperfections in Subversion's
> > SWIG bindings) which might stand in your way:
> > 1) SWIG does not automatically wrap arguments to callback
> > functions. Instead, you must create a C callback function which
> > manually converts arguments between Python and C using SWIG's APIs.
> > 2) SWIG does not automatically wrap pointers which are contained
> > inside arrays or hashes. Instead, you must write a typemap which
> > manually converts these pointers between Python and C using SWIG's
> > APIs.
> >
> > We already have written a large number of conversion functions which
> > accomplish (1) and (2), but they're really not very much fun to write.
> > It involves a lot of careful work and error checking.
> >
> > Once the SWIG typemaps are complete, we also suffer from another
> > problem: the generated SWIG bindings are undocumented. If you read
> > through the Subversion include files, you can understand a great deal
> > about how the Subversion bindings work, but your understanding will
> > not be complete until you understand the SWIG bindings as well.
> >
> > When I write functions which use the Python bindings, I often consult
> > the source code of the SWIG interface files to see how the Python
> > datatypes will be converted into Subversion datatypes, so as to make
> > sure that I am providing the correct arguments. We aren't completely
> > consistent about how we convert datatypes between Python and C, so you
> > often may have to consult the source code to make sure that it behaves
> > as you expect.
> >
> > That said, let's take another look at your primary task, which is to
> > write higher-level bindings for Subversion in Python. As written, our
> > project page suggests that these higher-level bindings for Subversion
> > must be based upon our lower-level SWIG bindings, but I'd like to
> > suggest another alternative: ctypes.
> >
> > As of Python 2.5, it's possible to access C datastructures directly
> > from Python. Using ctypes, you can access the complete Subversion API
> > via pure Python, without needing to write any complex SWIG or C
> > wrappers. This feature is also supported in older Python versions if
> > you download the ctypes module.
> >
> > ctypes is much simpler than SWIG, and supports many key features that
> > SWIG does not. For example, ctypes directly supports callback
> > functions, so you do not need to waste time creating verbose wrappers
> > in C for every callback function that Subversion supports. ctypes also
> > supports composite datatypes (e.g. an array of strings), so you don't
> > need to create individual typemaps for every possible composite
> > datatype. In fact, using ctypes, you don't need to create typemaps at
> > all -- you can just call the C functions directly, without worrying
> > about typemaps.
> >
> > If you use ctypes, you won't have to write (or modify) any code in C.
> > You can write everything in Python. As a result, your compile/debug
> > cycle will be very quick -- you won't have to recompile Subversion or
> > our Python bindings in order to test out a change to your higher-level
> > layer.
> >
> > Overall, I think that it would be easier to write higher-level Python
> > bindings using ctypes than it would to write them using our existing
> > SWIG bindings. In this case, you would truly be able to depend on
> > having a clear interface between your bindings and the underlying C
> > implementation.
> >
> > As part of your proposal, I'd love if you could write a simple Python
> > program which does a few simple things using Subversion. Perhaps you
> > can move a file from one location to another, directly in the
> > repository? This shouldn't be too hard to implement using ctypes.
> >
> > Don't forget to budget lots of time for test cases and documentation!
> >
> > Cheers,
> >
> > David
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
> > For additional commands, e-mail: dev-help@subversion.tigris.org
> >
>
>
> --
> C. Michael Pilato <cmpilato@collab.net>
> CollabNet <> www.collab.net <> Distributed Development On Demand
>
- application/pgp-signature attachment: stored
Received on Tue Mar 20 21:55:56 2007