This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex] 

Contents

  1. Beginning
    1. Using pygtkcompat
  2. How does PyGI work?
  3. Differences to the C API
    1. Constructors
    2. Passing arrays
    3. Output arguments
    4. GDestroyNotify
    5. Non-introspectable functions/methods
  4. Threads
  5. Overrides
  6. Porting from PyGTK 2 to PyGI GTK 3
    1. Step 1: The Great Renaming
    2. Step 2: Wash, rinse, repeat
    3. Step 3: Packaging changes
  7. Examples
  8. Comments
  9. Problems

Beginning

Starting with PyGObject 3.1.92 there's a module called pygtkcompat which will make it easier to port an application from PyGTK.

There are two different approaches to porting your application from PyGTK to gobject-introspection

  1. Using a PyGTK compatibility layer (pygtkcompat)

  2. Using a shell script which converts the callsites (pygi-convert.sh)

There are advantages and disadvantages with both:

  1. Using pygtkcompat makes it possible to focus on porting to Gtk 3.x while not changing anything
    • else, users and developers can keep on using the software as before.
  2. Using pygtkcompat allows you to support both Gtk 2.x and Gtk 3.x with the same code base

  3. Using pygi-convert.sh you can avoid using any layers and use the supported API directly

Using pygtkcompat

The pygtkcompat module provides a PyGTK compatible API on top of gobject-introspection which makes it possible to run your application on top of both PyGTK and gobject-introspection at the same time.

Before using it you should port your application to using latest API, available 2.24, for instance: 

  • widget.window should be widget.get_window()
container.child should be container.get_child()
widget.flags() & gtk.REALIZED should be container.get_realized()

and so on.

Once an application has been updated to the latest PyGTK API, you can then import pygtkcompat and enable the parts you need. For instance, to enable PyGTK compatible API on top of the Gtk 3.0 typelib, use the following: 

  • from gi import pygtkcompat

pygtkcompat.enable() 
pygtkcompat.enable_gtk(version='3.0')

That's it, if you're lucky enough and you're not using any strange/weird apis you should be able to run your application. If you want an app to be compatible with both PyGTK and PyGI, you can use the following technique: 

  • try:
    from gi import pygtkcompat
except ImportError:
    pygtkcompat = None

if pygtkcompat is not None:
    pygtkcompat.enable() 
    pygtkcompat.enable_gtk(version='3.0')

import gtk

    Note

    Porting the application from 2 to 3 is best covered in http://developer.gnome.org/gtk3/3.2/gtk-migrating-2-to-3.html. That usually includes things such as change expose-event to draw and do drawing with cairo.

How does PyGI work?

Initial GI support was added to pygobject in version 2.19.0 (August 2009), but the entire GI/pygobject/annotations stack really only stabilized in version 2.28, so that in practice you will need at least this version and the corresponding latest upstream releases of GTK and other libraries you want to use.

pygobject provides a gi.repository module namespace which generates virtual Python modules from installed typelibs on the fly. For example, if you have the GIR for GTK 3 installed, you can do:

and use it just like any other Python module.

Absolutely unexpected first example:

Let's look at the corresponding C declaration:

and the C call:

So what do we see here?

  1. The C API by and large remains valid in Python (and other languages using the GI bindings), in particular the structure, order, and data types of arguments. There are a few exceptions which are mostly due to the different way Python works, and in some cases to make it easier to write code in Python; see below for details. But this means that you can (and should) use the normal API documentation for the C API of the library. Devhelp is your friend!

  2. As Python is a proper object oriented language, pygobject (and in fact the GI typelib already) expose a GObject API as proper classes, objects, methods, and attributes. I. e. in Python you write 
    button = Gtk.Button()
button.set_label("foo")

instead of the C gobject syntax

As I mentioned above, this is in no way restricted to GTK, GNOME, or UI. For example, if you handle any kind of hardware and hotplugging, you almost certainly want to query udev, which provides a nice glib integration (with signals) through the gudev library. This example lists all block devices (i. e. hard drives, USB sticks, etc.):

See the GUDevClient documentation for the corresponding C API. GI is not even restricted to GObject, you can annotate any non-OO function based API with it. E. g. there is already a /usr/share/gir-1.0/xlib-2.0.gir (although it's horribly incomplete). These will behave as normal functions in Python (or other languages) as well.

Differences to the C API

The structure of method arguments is by and large the same in C and in GI/Python. There are some notable exceptions which you must be aware of:

Constructors

The biggest one is constructors. There is actually two ways of calling one:

The second is actually the recommended one, as it makes the meaning of the arguments more explicit, and also underlines the GObject best practice that a constructor should do nothing more than to initialize properties. But otherwise it's pretty much a matter of taste which one you use.

Passing arrays

Unlike C, higher level languages know how long an array is, while in the C API you need to specify that explicitly, either by terminating them with NULL or explicitly giving the length of the array in a separate argument. Which one is used is already specified in the annotations and thus in the typelib, so Python can automatically provide the right format without the developer needing to append an extra None or a separate len(my_array) argument.

For example, in C you have

In Python you can just call this as

and don't need to worry about the array size.

Output arguments

C functions can't return more than one argument, so they often use pointers which the function then fills out. Conversely, Python doesn't know about pointers, but can easily return more than one value as a tuple. The annotations already describe which arguments are "out" arguments, so in Python they become part of the return tuple: first one is the "real" return value, and then all out arguments in the same order as they appear in the declaration. For example:

In Python you would call this like

The Python help system shows the correct input, output and return argument expectations:

GDestroyNotify

Some GLib/GTK functions take a callback method and an extra user_data argument that is passed to the callback. In C they often also take a GDestroyNotify function which is run once all callbacks are done, in order to free the memory of user_data. As Python has automatic memory management, pygobject will take care of all this by itself, so you simply don't specify the GDestroyNotify argument. For example:

In Python you call this as

Non-introspectable functions/methods

When you work with PyGI for a longer time, you'll inevitably stumble over a method that simply doesn't exist in the bindings. These usually are marked with introspectable="0" in the GIR.

In the best case this is because there are some missing annotations in the library which don't have a safe default, so GI disables these to prevent crashes. They usually come along with a corresponding warning message from g-ir-scanner, and it's usually quite easy to fix these.

Another common case are functions which take a variable number of arguments, such as gtk_cell_area_add_with_properties(). Varargs cannot be handled safely by libgirepository. In these cases there are often alternatives available (such as gtk_cell_area_cell_set_property()). For other cases libraries now often have a ..._v() counterpart which takes a list instead of variable arguments.

Threads

For using threads with PyGObject, please see: Threads/Concurrency with Python and the GNOME Platform

Overrides

A specialty of pygobject is the possibility of replacing functions, methods, or classes of the introspected library with custom code, called "overrides". As the goal is to stay very close to the original API, they should be used and written sparsely, though. One major use case is to provide replacements for unintrospectable methods. For example, Gtk.Menu.popup() is not introspectable in GTK, but the GTK override implements this method in terms of Gtk.Menu.popup_for_device(), so in this case the override actually helps to get closer to the original API again. Another important case is automatic data type conversion, most prominently to allow passing unicode objects to methods which expect an UTF-8 encoded gchar*. This also actually helps to prevent workarounds in application code and maintain a clean API. Thirdly, overrides are useful if they help to massively ease development. For example it is quite laborious to do GDBus calls or GVariant constructions with the native Gio/GLib API. pygobject offers convenience overrides to make these a lot simpler and more Pythonic, but of course without actually breaking the original API.

Overrides should be quite easy to understand. In general you should not even be required to know about it, as most of them really just fix stuff to work as expected. :-)

Porting from PyGTK 2 to PyGI GTK 3

Note that this is really two migrations in one step, but is recommended as GTK2 still has a lot of breakage with PyGI. It is recommended to port applications to PyGI/GTK+ 3 first, then port to Python 3 as an additional step if Python 3 support is desired. Otherwise you can end up with a conflated and hard to track set of changes. See the GTK2 → GTK3 migration documentation.

If we compare the PyGTK vs. PyGI code for a "Hello" message box, we see that it's actually very similar in structure:

vs.

So PyGTK also does the representation of the C functions as proper classes and methods, thus if you port from PyGTK to PyGI, the structure by and large remains the same.

Step 1: The Great Renaming

The biggest part in terms of volume of code changed is basically just a renaming exercise. E. g. gtk.* now becomes Gtk.*, and gtk.MESSAGE_INFO becomes Gtk.MessageType.INFO. Likewise, the imports need to be updated: import gtk becomes from gi.repository import Gtk.

Fortunately this is is a mechanical task which can be automated. The pygobject git tree has a script pygi-convert.sh which is a long list of perl -pe 's/old/new/' string replacements.

It's really blunt, but surprisingly effective, and for small applications chances are that it will already produce something which actually runs. Note that this script is in no way finished, and should be considered a collaborative effort amongst porters. So if you have something which should be added there, please don't hesitate to open a bug or ping on IRC (#python on irc.gnome.org)). We will be happy to improve the script.

When you just run pygi-convert.sh in your project tree, it will work on all *.py files. If you have other Python code there which is named differently (such as bin/myprogram), you should run it once more with all these file names as argument.

Step 2: Wash, rinse, repeat

Once the mechanical renamings are out of the way, the tedious and laborious part starts. As Python does not have a concept of "compile-time check" and can't even check that called methods exist or that you pass the right number of parameters, you now have to enter a loop of "start your program", "click around until it breaks", "fix it", "goto 1".

The necessary changes here are really hard to generalize, as they highly depend on what your program actually does, and this will also involve the GTK 2 → 3 parts. One thing that comes up a lot are pack_start()/pack_end() calls. In PyGTK they have default values for expand, start, and padding attributes, but as GTK does not have them, you won't have them in PyGI either (see bgo#558620 - Add default values).

/!\ Note that you can't do a migration halfway: If you try to import both gtk and gi.repository.Gtk, you'll get nothing but program hangs and crashes, as you are trying to work with the same library in two different ways. You can mix static and GI bindings of different libraries though, such as dbus-python and gi.repository.Gtk.

If your application uses plugins, you can use libpeas. It is a GObject plugins library that support C, Python and Javascript languages though introspection.

Step 3: Packaging changes

After you have your code running with PyGI and committed it to your branch and released it, you need to update the dependencies of your distro package for PyGI. You should grep your code for "gi.repository" and collect a list of all imported typelibs, and then translate them into the appropriate package name. For example, if you import "Gtk, Notify, Gudev" you need to add dependencies to the packages which ship them:

At the same time you should drop the old static bindings, like python-gtk2, python-notify, etc.

Finally you should also bump the version of the pygobject dependency to (>= 2.28) to ensure that you run with a reasonably bug free PyGI.

Examples

Comments

One of the biggest challenges in porting is that all of the constants have changed names. The above pygi-convert.sh script gives a good idea about what the new names are, but if you have any problems, refer to the relevant .gir file directly. For example, if your old code says "gtk.TREE_VIEW_COLUMN_AUTOSIZE" and you're not sure what the new code should be, search in /usr/share/gir-1.0/Gtk-2.0.gir for "COLUMN_AUTOSIZE", and you'll find some code that looks like this: 

    <enumeration name="TreeViewColumnSizing"
                 glib:type-name="GtkTreeViewColumnSizing"
                 glib:get-type="gtk_tree_view_column_sizing_get_type"
                 c:type="GtkTreeViewColumnSizing">
      <member name="grow_only"
              value="0"
              c:identifier="GTK_TREE_VIEW_COLUMN_GROW_ONLY"
              glib:nick="grow-only"/>
      <member name="autosize"
              value="1"
              c:identifier="GTK_TREE_VIEW_COLUMN_AUTOSIZE"
              glib:nick="autosize"/>
      <member name="fixed"
              value="2"
              c:identifier="GTK_TREE_VIEW_COLUMN_FIXED"
              glib:nick="fixed"/>
    </enumeration>

Looking at that, you can determine the new constant name. It starts with "Gtk", then a period, then the enumeration name ("TreeViewColumnSizing"), then another period, then the member name in ALL CAPS ("AUTOSIZE"). So, this tells you to change "gtk.TREE_VIEW_COLUMN_AUTOSIZE" into "Gtk.TreeViewColumnSizing.AUTOSIZE"

Problems

2024-10-23 11:37