From Old To New Python GTK

I am a pretty terrible programmer. Anyone who has read my code can see that. Unfortunately, I tend to have lots of ideas about how we can use technology in different ways, hence why I write some code. Examples of this have included Lernid, Acire, RaccoonShow, and Jokosher.

Fortunately (or unfortunately, depending on your view), I have had Python and GTK to serve my needs here. Python, with it’s awesome batteries-included range of facilities and GTK as a simple yet flexible toolkit has allowed me to create implementations of the ideas that I have dreamed of. I started using these tools many years ago, and they have always provided a simple and effective toolset for me.

My preferred toolset of choice. One day…

Having not written any code for a while, I got the itch this weekend to start writing the trophy helper app that I wrote about as part of the accomplishments system spec that I created with Stuart Langridge and Daniel Holbach. I thought this would be a good opportunity to brush up on my skills, given that PyGTK is dead and the new world is instead the GIR approach to GTK. In a nutshell, this is where the language bindings basically match the C API for GTK thus reducing the need for people to maintain different language bindings.

Of course, this is a good thing: less work for volunteers in maintaining multiple-language support for GTK and a consistent API is good. Unfortunately, I found getting started with this new world a little more complex than I imagined.

From reading the documentation it suggested that all I needed to do was to import Gtk from gi.repository and instead of creating widgets with gtk.<foo> that they would be Gtk.<foo>. The docs suggested a few other lexical adjustments, but not much more than that. There is even a pygi-convert.sh script that can convert older PyGTK code over to the new PyGI way. Unfortunately the script didn’t work for me, so I instead used it as a cheat-sheet for things that needed changing. Sadly, it seemed like some things were not covered in the script.

An example of this included when I was creating a ListStore. In PyGTK code I could add a gtk.gdk.Pixbuf to the ListStore for an icon, but I had a difficult time trying to figure out the new way to describe this. I tried Gtk.gdk.Pixbuf and Gtk.Gdk.Pixbuf but had no luck. Fortunately the awesome Ryan Lortie informed me that it needed to be GdkPixbuf.Pixbuf. Another example of this was gtk.SORT_ASCENDING in my original code and the new Gtk.SortType.ASCENDING in the new code. It seems like various functionality in GTK has been moved around and re-factored.

Unfortunately I could not find any documentation to help me with this. Sure, the C docs are available online, but I am not a C programmer; I am (in the most generous and understanding way) a Python programmer and where I previously had a pretty decent tutorial and reference guide to PyGTK, as a desktop app developer I no longer have these resources to help me. Even though I am not a fantastic programmer, I have written enough Python and GTK code to fumble my way through writing various apps, and if it stumped me as a relatively old hand, I wonder how a brand new developer would get on.

Pictured: old hand.

Now, this may sound a little critical, but it is not mean’t to be. I have tremendous respect for the GTK team, and I am hugely thankful to them for all their hard work. I am also thankful for the team that has worked on the GIR support so that multiple language support can be more efficiently provided. Thanks to all you folks for providing great tools that let a programming numpty such as myself be able to write Free Software.

I just wanted to share this because I feel like these tools are missing the final component: if we had a good solid set of reference documentation generated for each language (naturally, Python is the language I mainly care about), this would help novice and established developers use GTK more effectively. From my personal experience, my patience started wearing pretty thin when I felt like I didn’t have anywhere to find help as I navigated C documentation to try and figure out how the API fitted into my Python application. A good solid Python reference manual would have resolved this issue, and from what I understand, this could potentially be generated from the GIR files. Unfortunately, I don’t think I have the skills to help solve this problem, so I figured the best I could do was to share my story and see if anyone would be interested in helping to solve this problem.

If so, thanks in advance, and thanks again to the GTK team for all your hard work!

Update

I found this excellent documentation after publishing this entry. This provides exactly the kind of documentation I was looking for. Thanks to anyone who helped contribute to this!

20 Comments

I also had few problems with C API manual at first. Then you get the hang of it (with lots of googling. Just yesterday I realized that there’s a part of Gtk/Cairo that didn’t make it into GIR, so I can’t implement one feature that I’d like. :/

As a python programmer myself, I’m used to the excellent documentation of doc.djangoproject.com and of course python itself. Even newer graphical toolkits like kivy.org/docs are already much better documented than every gir based library I have ever seen.
But that is not all: the automatic documentation from gir files would still lead to very bad documentation. Good documentation is much more than an API reference.

And a good pythonic interface is much more than an automatically generated python binding! A perfect example is the singlet project started by Michael Hall, which is a pythonic interface to all the gir based stuff that unity lenses would require otherwise.
Or the kivy way of handling videos (backed by gstreamer): this is the full code needed to load and play a video from anywhere:

This is what a python library should look like. If you compare this to the automically generated gstreamer python interface, the differences are amazing. And this is not solely due to the additional code that went into hiding the details. Its also that the C interfaces need to have methods which are totally useless in Python: you dont need get_int64, get_bool, … in Python, there are properties (replacing the explicit get_ and set_ routines) and there is duck-typing/dynamic typing (int64 or int or double or some custom datatype: as long as the mathematical functions work, I don’t care).

I was very excited when I first heard about the gobject introspection and automatic language binding, because (as you said) it reduces the amount of work needed to get bindings. But what seems to have happened is that work in general for other languages got reduced. I’m not so sure anymore if gir was really a good idea for anyone other than C developers.

Maybe what you need is not documentation but code completion! With a good IDE that can introspect libraries, all is auto-completed (similarly to when you press tab in the console to find the exact term you want to use).

Thanks Jono for bringing this up. I too was initially really happy to see python(PyGTK) G-Object/GIR-ified. The whole automated binding stuff was an easy sell for me. But PyGTK had some of the best documentation out there. The sheer number of hours invested in writing that excellent documentation surely outnumbered all the programming work done in this conversion process. The conversion is now done but the documentation is simply not there and no amount of automation will ever substitute for the loving attention to detail and work that went into now defunct PyGTK documentation. And unfortunately i see little likelihood that there will ever be as good documentation coming forth as what we had with PyGTK. The surge in Vala/javascript/html5/css programming alternatives has taken the vast majority of the wind out of the sails which would be necessary for that amount of work to poured into producing such great documentation. I wish I had an answer-one step forward two steps back….

The doc stuff started at the hackfest during the Desktop Summit but it needs volunteers to pick it up again. You can also jump on #python on GNOME’s irc servers. I’m no longer working on the project as I have moved team inside of Red Hat and have little time to hack on it. I figured it would take another year of full time work to fix all the most used edge cases and get the docs up to the level of PyGTK. Other than that the project is actually in pretty good shape. Sebp has a nice tutorial http://readthedocs.org/docs/python-gtk-3-tutorial/en/latest/index.html and there is a short porting guide here – https://live.gnome.org/PyGObject/IntrospectionPorting. There are also plenty of small demos mirroring the GTK+ C demos in the source tree.

The doc stuff started at the hackfest during the Desktop Summit but it needs volunteers to pick it up again. You can also jump on #python on GNOME’s irc servers. I’m no longer working on the project as I have moved team inside of Red Hat and have little time to hack on it. I figured it would take another year of full time work to fix all the most used edge cases and get the docs up to the level of PyGTK. Other than that the project is actually in pretty good shape. Sebp has a nice tutorial http://readthedocs.org/docs/python-gtk-3-tutorial/en/latest/index.html and there is a short porting guide here – https://live.gnome.org/PyGObject/IntrospectionPorting. There are also plenty of small demos mirroring the GTK+ C demos in the source tree.

I also was quite enthusiastic about the switch to PyGI. Now, that I am trying to port my current projects from PyGTK to PyGI for Precise, I am quite frustated.

It is not that static bindings had no issues. E.g., the EDS bindings were far from complete, and having dynamic bindings is a big plus. But at this point, the annotations are at least as incomplete as the previous static bindings. I can’t port one project to PyGI, because it uses goocanvas, and the GI-bindings are not yet in Ubuntu. I can’t start one new project because the PyGI-bindings for libfolks are buggy as hell.

I believe that there are good reasons for GI. And it might even hold a bright future. But for the time of the transition (which already lasts a few years and probably will take some more), it makes things worse for application developers. Incomplete annotations/bindings, non-native coding style, and missing docs are probably the biggest hurdles we are currently facing.

Looks like most of the stuff I know about has already been linked to, but I also wanted to point out the great work going on at http://developer.gnome.org/ It’s not complete yet (especially the Python stuff), but it looks really promising as an introduction to programming for GNOME/Ubuntu. Hopefully http://developer.ubuntu.com will be able to incorporate/link to some of that stuff.

More importantly, I really hope Quickly gets on the GIR bandwagon soon. It’s the closest thing Ubuntu has to a blessed tool set/development workflow, and it’s currently leading new Ubuntu application developers down a dead end path using the old PyGTK stuff.

* Is there a page that outlines how to get involved in the project to generate docs from the GIR files? If there is a page that outlines how complete the project is, what needs doing, and how people can participate, I would love to help spread the word.

* Is there a snapshot online of the Python docs generated for the GIR files?

Jono nice blog post,
I think this post is somewhat relevant to myself.
I am by trade a LAMP dev so I approach things with the PHP/JavaScript mentality NOT the C/C++ mentality (different but beautiful schools of thought).
I have been poking around Python for a year or 2 and next week I am going to work a contract that demands it! woot 🙂

I do find that this is a frustration I have, python does look beautiful (a bit like Pearl but… you know).

Using Gtk or many other modules I often find that the documentation/forums/YouTubery only describes the absolute basics of bootstrapping a “hello world” type app, and that when I start digging I find all the documentation for advanced things is in the mindset of (ok C++ guys this is how you do what we do in C with python…).

I have oodles of respect for C++ devs as I think it’s cool, such an opportunity out there for “casual development”.

I’m likely to not have time to work on it after the hackfest, so unless people start stepping up and contributing, we won’t have Python API docs for Gtk+ > 2

IMO what is most needed now is someone to document what we have today, consolidate the existing documentation and start a roadmap (so no programming required). Volunteers are more likely to come when that’s done.

Sure. And I fully understand that C developers don’t want to spend time writing the bindings for languages that they don’t use. It’s just that this does not make the situation for non-C languages any better. And the result is that non-C language developers will not likely use gtk in the future. I have started, after the introspection switch, to work with Qt, Kivy, and even Hmlt5 in webkit. All seemed easier to use then gtk. That is not meant as a cheap threat (as in “I will use windows if you dont implement X…”) its really only meant as a description of the view of a python developer with little time for non-work related projects.