What's this all about? To start from the beginning, about Python. Although we are focusing here on PyGTK (especially because starting from Gnome 3 inclusive, it won't continue its development, so that means "renew or die"), this is about porting applications done with intermediate libs that work with GObject (gtk, gdk, webkit...) to GObject Introspection. So what's going to be told on this post is also valid for this other API's.

What's GObject Introspection (link and sublinks are recommended readings)? As can be read from the description from the web and the Debian package itself, it is a project for providing machine readable introspection data of the API of C libraries.

What is this for? It has many applications, such as automatic code generation for bindings (the most interesting one), API verification and documentation generation. About the most important point, we don't need anymore the bindings that we have been using so far (because the metadata that the bindings had are now stored directly in GObject), so it is one layer less of conflict and we can now access GObject libraries directly. This also allows us to make multi-language applications between languages from different levels (in instance, C and Python, Java... and even Javascript).

Where do we start from? We can start from this website. The reader should keep in mind, if you haven't already noticed, we're going to use Debian GNU / Linux Testing (currently Squeeze) as a base for this post, especially when making references to package and paths used since may be different for other distributions.

What do we need?

1. We must install first the following packages: gobject-introspection (tools for generating and processing the data of introspection), python-gobject (Python bindings for GObject library) and python-gi (modules that will allow dynamic linking and introspection in GObject-based applications). Note: in the near future (so that to the 2.26 of python-gobject?), python-gi package will disappear because it will be integrated into python-gobject.
2. Then we need the API files. These will define what can be ported to pygi (Python GObject Introspection). Regarding these API's, say on the one hand we have the typelibs (which would be the compiled files, the ones we are interested in to use in our apps) and on the other the girs (which would be the xml's representing the sources). Due to the current lack of documentation on the subject, these gir's can serve as such for the migration of our apps, as discussed below. In Debian, the path to find the typelibs is /usr/lib/girepository-1.0/ (for Gtk2) and /usr/lib/girepository-3.0/ (for Gtk3). To find/install API's present in repository packages, we can do a search for package names starting with gir1.0* (for Gtk2) or gir2.0* (Gtk3 suppose to be so). Here you have a sample search at packages.debian.org. If we install the gir's/xml's (for example, because we want to take a look at the methods or properties of an object as documentation*), we would need to install the development packages for that component (in instance, libwebkit-dev in the case of WebKit).
3. Then, when you already have the API's, we can start the process of porting code. On this first step, we are going to change the imports. Eg. instead of performing the typical import gtk, we would do a from gi.repository import Gtk instead. And we will do the same with all those libraries that want to use to GObject Introspection (from gi.repository import Gtk, Gdk, WebKit, ...).
4. That done, we can go to the most complicated step, which is the migration of the rest of the code. Given the novelty and immature of the matter, you can:
   • Start using tomeu's pygi_convert.sh script.
   • Take a look at the code of an already ported application.
   • Reading the gir's (xml's) as a kind of documentation.
   • Ask on IRC channels (like #python @ GIMPnet) or mailing lists.
   When the project reaches a more mature status, it will most likely crop up documentation and tutorials and howto's, but it is important to begin to look forward and at the same time go on supporting the project.
   
   * Tip: some things -attributes & methods- can also be seen with a dir(object).

To finish, comment that although the project (PyGi) reflects quite recent development activity and is not yet stabilized, PyGTK developers are urged to start porting applications as soon as possible to help find potential problems and make advance/mature the project. For those interested in Linux-distribution packages, here you have a recent commentary on versions for different distros (although the more adventurous can build their own binaries from sources).

Regarding Naufrago! (here at gnomefiles), the little project that has motivated this post, let me say that some migration from PyGTK (and others) to PyGi has been done. But as long as I'm using Debian GNU/Linux Testing distribution packages, I'm stuck with changes present on python-gobject version 2.26 that are not on current testing/unstable/experimental packages. So I'll wait for maintainers to have it ready to proceed for further steps in my code. Keep up the good work!