Fwd: Current state of Python bindings.

["Mark Doffman" <Mark Doffman codethink co uk>]

---------- Forwarded message ----------
From: Mark Doffman <Mark Doffman codethink co uk>
Date: Aug 28, 2007 1:33 AM
Subject: Current state of Python bindings.
To: me pvanhoof be, Rob Taylor <rob taylor codethink co uk>

Hello, 

I have been looking at helping out with the Python bindings for Tinymail, to try and put a Road-map together for their completion. Currently the Python bindings have lapsed a little and don't seem to be functional. I have been unable to load the tinymail-camel library, and as such get the Python-demo going. The tinymail-camel library has difficulty with the TinySessionCamel and TinyStreamCamel. As these are types based on CamelObject, and internal, they may need to be removed from the interface generation. Philip has indicated that there are a few more issues lurking beneath this before the demo code works properly, probably related to the incomplete wrapping of the Tinymail interface mentioned below. Nevertheless the first step must be to get the demo code going, and I'll be looking to do that soon.

Completing the basic API:

Presumably as Tinymail has moved on, the .override files used to put together the bindings have become incomplete. There are a number of methods and functions that are not wrapped. An overview of the parts of Tinymail and the methods that still need wrapping are below:

tinymail
----------
Old style constructors(4)
Unwrapped methods(30)
Unwrapped functions(3) 
Unknown arguments(24)

tinymailui-gtk
-----------------
Old style constructors(4)
Unwrapped functions(2)
Unknown arguments(1)

tinymail-camel
-------------------
Old style constructors(3)
Unwrapped methods(6)
Unwrapped functions(2)
Unknown arguments(6)

(Old style constructors warning is an issue with subclassing types that means if signals or parameters are defined with the new type only gobject__init__ can be used in python constructor. Probably not a big issue.)

There are a number of easy fixes amongst the functions that still need wrapping, such as class methods that have been wrongly allocated as module functions - these can be fixed by small changes to the .override file. There are many functions that will have to be wrapped by hand, such as those requiring a callback / returning values via their arguments. I envisage that completing the API so pygtk-codegen has 100% coverage is a medium body of work encompassing perhaps a couple of man weeks

API Test coverage - Nothings complete until its tested. So much of the wrapping is automatically generated and presumed correct - but we will need to test the interface as much as possible. Perhaps the libtinymail-tests could be converted to python to exercise the interfaces?

Extensions to the basic API -

The basic Python API would consist of the work done above, Tinymail classes are available in Python for use. PyGObject and the pygtk-codegen tools have the ability to make the virtual functions of a GType available for use in Python. This would allow python code to, for example, implement a TnyMsg interface and use the wrapped TnyGtkMsgView class to display that message. As a framework for developing applications I think that this is a fairly essential feature. 

I have been unable to build the python bindings with virtual methods using scanvirtuals.py. The tool creates errors in the .defs file - multiple declarations of the same method.

Completing this stage would involve checking that all virtual functions, in interfaces or otherwise are, properly wrapped.

Pythonification -
This is something that will beautify the bindings done once they are essentially complete. (And a stage PyGtk seems to have been going through for a while). 

Fields - People using the Python bindings may wish to be able to access some fields of an object directly. (eg 
widget.window) There seems to be methods for doing this already in the PyGtk code generators. This may be a case of changing the .defs file. It requires some thought from someone who knows the interfaces well to decide WHICH fields are suitable for simple access.

Iterators - There is other perhaps more difficult work for example, python provides its own iterator API, and interface for type implementation of this. How does it fit in with the TinyMail iterator interface?

Docs - Provide meaningful doc strings. 

I need some help sorting this all out into something with more near term goals and a time line. I think that the python bindings to be considered complete and usable should be declaring virtual functions. They also need decent testing, either by unit testing, or completing a mail client that stretches the interface to the extent we want. 

Thoughts please,

Thanks

Mark