PyMaemo/Accessing APIs without Python bindings

(Initializing libosso-abook)
(Accessing Items in a GList)
 
(15 intermediate revisions not shown)
Line 1: Line 1:
-
<b style="color:red">This is an on-going document, and will be linked on the PyMaemo main page once finished</b>
 
-
 
== Introduction ==
== Introduction ==
Line 11: Line 9:
This document is not meant to be a complete <code>ctypes</code> guide; for that, be sure to read the [http://docs.python.org/library/ctypes.html official API documentation]. It is assumed that you have read that document before continuing.
This document is not meant to be a complete <code>ctypes</code> guide; for that, be sure to read the [http://docs.python.org/library/ctypes.html official API documentation]. It is assumed that you have read that document before continuing.
-
== Basic usage ==
+
== Basic Usage ==
-
 
+
-
Let's say you want to use printf() from the GNU C Library. All you need in Python is:
+
-
 
+
-
import ctypes
+
-
libc = ctypes.CDLL('libc.so.6')
+
-
libc.printf('Hello world!')
+
 +
Let's say you want to use <code>printf()</code> from the GNU C Library. All you need in Python is:
 +
<source lang="python">
 +
import ctypes
 +
libc = ctypes.CDLL('libc.so.6')
 +
libc.printf('Hello world!')
 +
</source>
In a few words, you create an object correspondent to the library you need and use it to call the function directly. You can also store the functions in plain python objects to use them easily later:
In a few words, you create an object correspondent to the library you need and use it to call the function directly. You can also store the functions in plain python objects to use them easily later:
-
 
+
<source lang="python">
-
c_printf = libc.printf
+
c_printf = libc.printf
-
c_printf('Hello libc')
+
c_printf('Hello libc')
-
 
+
</source>
Remember that those are C functions, not Python ones, so you must supply arguments of the correct type to avoid undefined behavior (such as segmentation faults). As an example, if an integer is passed to the above function, you get
Remember that those are C functions, not Python ones, so you must supply arguments of the correct type to avoid undefined behavior (such as segmentation faults). As an example, if an integer is passed to the above function, you get
Line 31: Line 29:
== Initializing libosso-abook ==
== Initializing libosso-abook ==
-
libosso-abook needs to be initialized by calling [http://maemo.org/api_refs/5.0/5.0-final/libosso-abook/libosso-abook-osso-abook-init.html#osso-abook-init osso-abook-init()]. This is similar to the example above, but a little more complex because the function takes three pointers: argc, argv and the OSSO context. First of all, you must create a osso.Context instance using the "osso" module (provided python-osso):
+
libosso-abook needs to be initialized by calling [http://maemo.org/api_refs/5.0/5.0-final/libosso-abook/libosso-abook-osso-abook-init.html#osso-abook-init osso-abook-init()]. This is similar to the example above, but a little more complex because the function takes three pointers: argc, argv and the OSSO context. First of all, you must create a <code>osso.Context</code> instance using the "osso" module (provided by python-osso):
-
 
+
<source lang="python">
-
import osso
+
import osso
-
+
-
osso_ctx = osso.Context("test_abook", "0.1")
+
 +
osso_ctx = osso.Context("test_abook", "0.1")
 +
</source>
Note: there is no documentation for python-osso yet, so see the C documentation for [http://maemo.org/api_refs/5.0/5.0-final/libosso/group__Init.html#g05d45d1e72c2cd74f665086225141431 osso_initialize()] for details about osso.Context() arguments. Note that only "application" and "version" attributes are used in Python.
Note: there is no documentation for python-osso yet, so see the C documentation for [http://maemo.org/api_refs/5.0/5.0-final/libosso/group__Init.html#g05d45d1e72c2cd74f665086225141431 osso_initialize()] for details about osso.Context() arguments. Note that only "application" and "version" attributes are used in Python.
Next, load and initialize libosso-abook library:
Next, load and initialize libosso-abook library:
 +
<source lang="python">
 +
import sys
 +
import ctypes
 +
# be sure to import gtk before calling osso_abook_init()
 +
import gtk
-
import sys
+
osso_abook = ctypes.CDLL('libosso-abook-1.0.so.0')
-
+
argv_type = ctypes.c_char_p * len(sys.argv)
-
osso_abook = ctypes.CDLL('libosso-abook-1.0.so.0')
+
argv = argv_type(*sys.argv)
-
argv_type = ctypes.c_char_p * len(sys.argv)
+
argc = ctypes.c_int(len(sys.argv))
-
argv = argv_type(*sys.argv)
+
osso_abook.osso_abook_init(ctypes.byref(argc), ctypes.byref(argv), hash(osso_ctx))
-
argc = ctypes.c_int(len(sys.argv))
+
</source>
-
osso_abook.osso_abook_init(ctypes.byref(argc), ctypes.byref(argv), hash(osso_ctx))
+
-
 
+
The byref() function returns a pointer to the given data. The hash() function returns the memory address of the argument.
The byref() function returns a pointer to the given data. The hash() function returns the memory address of the argument.
-
== Calling a function which returns a GObject (i.e. a constructor) ==
+
== Calling a Function Which Returns a GObject ==
Every GObject instance created by a C library must have a corresponding Python object, so that it can be manipulated on Python code. This object, which acts like a "wrapper" around the C pointer, is created using the pygobject_new() C function. Unfortunately, pygobject_new() is not a plain function, but a macro which points to a function pointer in a struct (see /usr/include/pygtk-2.0/pygobject.h on the "#define pygobject_new ..." line), making it a little more complex to be called from Python. The snippet of code below, borrowed from [http://faq.pygtk.org/index.py?req=show&file=faq23.041.htp PyGTK FAQ], will take care of this:
Every GObject instance created by a C library must have a corresponding Python object, so that it can be manipulated on Python code. This object, which acts like a "wrapper" around the C pointer, is created using the pygobject_new() C function. Unfortunately, pygobject_new() is not a plain function, but a macro which points to a function pointer in a struct (see /usr/include/pygtk-2.0/pygobject.h on the "#define pygobject_new ..." line), making it a little more complex to be called from Python. The snippet of code below, borrowed from [http://faq.pygtk.org/index.py?req=show&file=faq23.041.htp PyGTK FAQ], will take care of this:
 +
<source lang="python">
 +
# ctypes wrapper for pygobject_new(), based on code snippet from
 +
# http://faq.pygtk.org/index.py?req=show&file=faq23.041.htp
 +
class _PyGObject_Functions(ctypes.Structure):
 +
    _fields_ = [
 +
        ('register_class',
 +
            ctypes.PYFUNCTYPE(ctypes.c_void_p, ctypes.c_char_p,
 +
            ctypes.c_int, ctypes.py_object, ctypes.py_object)),
 +
        ('register_wrapper',
 +
            ctypes.PYFUNCTYPE(ctypes.c_void_p, ctypes.py_object)),
 +
        ('register_sinkfunc',
 +
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_void_p)),
 +
        ('lookupclass',
 +
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_int)),
 +
        ('newgobj',
 +
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_void_p)),
 +
    ]
-
# ctypes wrapper for pygobject_new(), based on code snippet from
+
class PyGObjectCPAI(object):
-
# http://faq.pygtk.org/index.py?req=show&file=faq23.041.htp
+
    def __init__(self):
-
class _PyGObject_Functions(ctypes.Structure):
+
        import gobject
-
    _fields_ = [
+
        py_obj = ctypes.py_object(gobject._PyGObject_API)
-
        ('register_class',
+
        addr = ctypes.pythonapi.PyCObject_AsVoidPtr(py_obj)
-
            ctypes.PYFUNCTYPE(ctypes.c_void_p, ctypes.c_char_p,
+
        self._api = _PyGObject_Functions.from_address(addr)
-
            ctypes.c_int, ctypes.py_object, ctypes.py_object)),
+
-
        ('register_wrapper',
+
-
            ctypes.PYFUNCTYPE(ctypes.c_void_p, ctypes.py_object)),
+
-
        ('register_sinkfunc',
+
-
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_void_p)),
+
-
        ('lookupclass',
+
-
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_int)),
+
-
        ('newgobj',
+
-
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_void_p)),
+
-
    ]
+
-
class PyGObjectCPAI(object):
+
    def pygobject_new(self, addr):
-
    def __init__(self):
+
        return self._api.newgobj(addr)
-
        py_obj = ctypes.py_object(gobject._PyGObject_API)
+
</source>
-
        addr = ctypes.pythonapi.PyCObject_AsVoidPtr(py_obj)
+
Adding this to your code, you will be able to create Python objects from an arbitrary GObject pointer, simply using something like:
-
        self._api = _PyGObject_Functions.from_address(addr)
+
<source lang="python">
 +
capi = PyGObjectCPAI()
 +
c_obj = c_function_returning_gobject(...)
 +
obj = capi.pygobject_new(c_obj)
 +
</source>
 +
== Creating a OssoABookContactChooser Instance ==
-
    def pygobject_new(self, addr):
+
As an example of a GObject instantiation, let's call the <code>osso_abook_contact_chooser_new()</code> constructor from Python, which creates a "contact chooser" dialog useful to select one of more contacts:
-
        return self._api.newgobj(addr)
+
<source lang="python">
 +
capi = PyGObjectCPAI()
 +
c_chooser = osso_abook.osso_abook_contact_chooser_new(None, "Choose a contact")
 +
chooser = capi.pygobject_new(c_chooser)
 +
</source>
 +
After this, you can use <code>chooser</code> like any other GObject in Python, including calling inherited methods:
 +
<source lang="python">
 +
chooser.run()
 +
chooser.hide()
 +
</source>
 +
== Accessing Items in a GList ==
-
Adding this to your code, you will be able to create Python objects from an arbitrary GObject pointer, simply using something like:
+
Once the "contact chooser" dialog has run, you can get the selected contacts using:
 +
<source lang="python">
 +
contacts = osso_abook.osso_abook_contact_chooser_get_selection(c_chooser)
 +
</source>
 +
Note that you must pass the '''C Pointer''' to [http://maemo.org/api_refs/5.0/5.0-final/libosso-abook/OssoABookContactChooser.html#osso-abook-contact-chooser-get-selection osso_abook_contact_chooser_get_selection()], not the Python object.
-
capi = PyGObjectCPAI()
+
the <code>contacts</code> variable now holds a <code>GList</code> pointer. In order to access the items stored on this list, you need some Python code:
-
c_obj = c_function_returning_gobject(...)
+
<source lang="python">
-
obj = capi.pygobject_new(c_obj)
+
glib = ctypes.CDLL('libglib-2.0.so.0')
 +
def glist(addr):
 +
    class _GList(ctypes.Structure):
 +
        _fields_ = [('data', ctypes.c_void_p),
 +
                    ('next', ctypes.c_void_p)]
 +
    l = addr
 +
    while l:
 +
        l = _GList.from_address(l)
 +
        yield l.data
 +
        l = l.next
 +
</source>
 +
This function uses the yield statement to construct a so called [http://docs.python.org/tutorial/classes.html#generators generator]. The actual GList manipulation is made using functions from libglib library. This generator makes it very easy to iterate over the items:
 +
<source lang="python">
 +
for i in glist(contacts):
 +
    get_display_name = osso_abook.osso_abook_contact_get_display_name
 +
    get_display_name.restype = ctypes.c_char_p
 +
    print "%s\n" % get_display_name(i)
 +
</source>
 +
Here, we use [http://maemo.org/api_refs/5.0/5.0-final/libosso-abook/OssoABookContact.html#osso-abook-contact-get-display-name osso_abook_contact_get_display_name()] to get the contact's display name, but you can call virtually any function using the same approach.
-
== Creating a OssoABookContactChooser instance ==
+
Once you are done with the <code>GList</code> manipulation, you should free its memory:
-
As an example of a GObject instantiation, let's call the osso_abook_contact_chooser_new() constructor from Python, which creates a "contact chooser" dialog useful to select one of more contacts:
+
With some functions (NOT this one, see docs), you should also unref the list items first:
 +
<source lang="python">
 +
for i in glist(stuffs):
 +
  gobject.g_object_unref(i)
 +
</source>
-
c_chooser = osso_abook.osso_abook_contact_chooser_new(None, "Choose a contact")
+
Then free the list itself:
-
chooser = capi.pygobject_new(c_chooser)
+
<source lang="python">
 +
glib.g_list_free(contacts)
 +
</source>
-
After this, you can use <code>chooser</code> like any other GObject in Python, including calling inherited methods:
+
== Final Words ==
 +
 
 +
This document purpose is to give a basic understanding necessary to use ctypes to explore C libraries, specially ones that manipulate GObject. Notably, we do not describe how to define callbacks, but this is left as an exercise for the reader. Again, be sure to read the [http://docs.python.org/library/ctypes.html#callback-functions ctypes documentation] if you are interested in more advanced techniques.
 +
 
 +
See also more usage examples [[/More examples|here]].
-
chooser.run()
+
[[Category:Python]]
-
chooser.hide()
+

Latest revision as of 11:02, 12 September 2010

Contents

[edit] Introduction

There are many libraries written in C that do not have native Python bindings yet. In Maemo, one of such libraries is libosso-abook, which manipulates the address book on Maemo devices.

While a full binding is very useful, in most cases you need to use just a couple of functions and data structures to get your work done. Instead of waiting for a binding to be implemented, you can use Python's ctypes module, which allows to directly call functions and access data structures from C libraries.

This document will explain how to do call C library functions using ctypes, using mainly libosso-abook as an example. The idea has been borrowed from Hermes application source code, which in turn is based on the trick described on the PyGTK FAQ.

This document is not meant to be a complete ctypes guide; for that, be sure to read the official API documentation. It is assumed that you have read that document before continuing.

[edit] Basic Usage

Let's say you want to use printf() from the GNU C Library. All you need in Python is:

import ctypes
libc = ctypes.CDLL('libc.so.6')
libc.printf('Hello world!')

In a few words, you create an object correspondent to the library you need and use it to call the function directly. You can also store the functions in plain python objects to use them easily later:

c_printf = libc.printf
c_printf('Hello libc')

Remember that those are C functions, not Python ones, so you must supply arguments of the correct type to avoid undefined behavior (such as segmentation faults). As an example, if an integer is passed to the above function, you get

>>> c_printf(1)
Segmentation fault (core dumped)

[edit] Initializing libosso-abook

libosso-abook needs to be initialized by calling osso-abook-init(). This is similar to the example above, but a little more complex because the function takes three pointers: argc, argv and the OSSO context. First of all, you must create a osso.Context instance using the "osso" module (provided by python-osso):

import osso
 
osso_ctx = osso.Context("test_abook", "0.1")

Note: there is no documentation for python-osso yet, so see the C documentation for osso_initialize() for details about osso.Context() arguments. Note that only "application" and "version" attributes are used in Python.

Next, load and initialize libosso-abook library:

import sys
import ctypes
# be sure to import gtk before calling osso_abook_init()
import gtk
 
osso_abook = ctypes.CDLL('libosso-abook-1.0.so.0')
argv_type = ctypes.c_char_p * len(sys.argv)
argv = argv_type(*sys.argv)
argc = ctypes.c_int(len(sys.argv))
osso_abook.osso_abook_init(ctypes.byref(argc), ctypes.byref(argv), hash(osso_ctx))

The byref() function returns a pointer to the given data. The hash() function returns the memory address of the argument.

[edit] Calling a Function Which Returns a GObject

Every GObject instance created by a C library must have a corresponding Python object, so that it can be manipulated on Python code. This object, which acts like a "wrapper" around the C pointer, is created using the pygobject_new() C function. Unfortunately, pygobject_new() is not a plain function, but a macro which points to a function pointer in a struct (see /usr/include/pygtk-2.0/pygobject.h on the "#define pygobject_new ..." line), making it a little more complex to be called from Python. The snippet of code below, borrowed from PyGTK FAQ, will take care of this:

# ctypes wrapper for pygobject_new(), based on code snippet from
# http://faq.pygtk.org/index.py?req=show&file=faq23.041.htp
class _PyGObject_Functions(ctypes.Structure):
    _fields_ = [
        ('register_class',
            ctypes.PYFUNCTYPE(ctypes.c_void_p, ctypes.c_char_p,
            ctypes.c_int, ctypes.py_object, ctypes.py_object)),
        ('register_wrapper',
            ctypes.PYFUNCTYPE(ctypes.c_void_p, ctypes.py_object)),
        ('register_sinkfunc',
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_void_p)),
        ('lookupclass',
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_int)),
        ('newgobj',
            ctypes.PYFUNCTYPE(ctypes.py_object, ctypes.c_void_p)),
    ]
 
class PyGObjectCPAI(object):
    def __init__(self):
        import gobject
        py_obj = ctypes.py_object(gobject._PyGObject_API)
        addr = ctypes.pythonapi.PyCObject_AsVoidPtr(py_obj)
        self._api = _PyGObject_Functions.from_address(addr)
 
    def pygobject_new(self, addr):
        return self._api.newgobj(addr)

Adding this to your code, you will be able to create Python objects from an arbitrary GObject pointer, simply using something like:

capi = PyGObjectCPAI()
c_obj = c_function_returning_gobject(...)
obj = capi.pygobject_new(c_obj)

[edit] Creating a OssoABookContactChooser Instance

As an example of a GObject instantiation, let's call the osso_abook_contact_chooser_new() constructor from Python, which creates a "contact chooser" dialog useful to select one of more contacts:

capi = PyGObjectCPAI()
c_chooser = osso_abook.osso_abook_contact_chooser_new(None, "Choose a contact")
chooser = capi.pygobject_new(c_chooser)

After this, you can use chooser like any other GObject in Python, including calling inherited methods:

chooser.run()
chooser.hide()

[edit] Accessing Items in a GList

Once the "contact chooser" dialog has run, you can get the selected contacts using:

contacts = osso_abook.osso_abook_contact_chooser_get_selection(c_chooser)

Note that you must pass the C Pointer to osso_abook_contact_chooser_get_selection(), not the Python object.

the contacts variable now holds a GList pointer. In order to access the items stored on this list, you need some Python code:

glib = ctypes.CDLL('libglib-2.0.so.0')
def glist(addr):
    class _GList(ctypes.Structure):
        _fields_ = [('data', ctypes.c_void_p),
                    ('next', ctypes.c_void_p)]
    l = addr
    while l:
        l = _GList.from_address(l)
        yield l.data
        l = l.next

This function uses the yield statement to construct a so called generator. The actual GList manipulation is made using functions from libglib library. This generator makes it very easy to iterate over the items:

for i in glist(contacts):
    get_display_name = osso_abook.osso_abook_contact_get_display_name
    get_display_name.restype = ctypes.c_char_p
    print "%s\n" % get_display_name(i)

Here, we use osso_abook_contact_get_display_name() to get the contact's display name, but you can call virtually any function using the same approach.

Once you are done with the GList manipulation, you should free its memory:

With some functions (NOT this one, see docs), you should also unref the list items first:

for i in glist(stuffs):
   gobject.g_object_unref(i)

Then free the list itself:

glib.g_list_free(contacts)

[edit] Final Words

This document purpose is to give a basic understanding necessary to use ctypes to explore C libraries, specially ones that manipulate GObject. Notably, we do not describe how to define callbacks, but this is left as an exercise for the reader. Again, be sure to read the ctypes documentation if you are interested in more advanced techniques.

See also more usage examples here.