Project Cazaril

This page outlines the list of APIs the PyGTK developers would like to break. But please note that there are currently no plans to break the API. This list is just to help evaluate the potential usefulness (or not) of ever breaking the API. If the API would ever be broken, we would need two parallel installable pygtk versions: one the new API, and one with old one for compatibility.

Trivia: Cazaril is the main character in Lois McMaster Bujold's book The Curse of Chalion.

API Plans

deprecations

All currently deprecated functions/methods/variables would disappear.

unicode

All pygtk functions that accept strings can receive either utf-8 encoded 'str' objects, or 'unicode' objects. However, pygtk functions/methods that return strings, always return utf-8 encoded 'str' objects. The plan is to always return 'unicode' objects.

__new__

The constructors for GObjects are to be mapped to PyObject's tp_new / __new__, instead of tp_init / __init__

constructors' default values

The current inconsistencies with default values in pygtk constructors vs default values in the underlying gtk+ C library would be resolved. The default values should alwasy match.

gtk.binding_entry_* api breakage

It's unpythonic to ask type, value pairs! Instead of forcing int, 1 user of the API can do 1 and you can do type(1), 1 below

classmethods

functions which return an object of a type or is related to a certain type will be found on the type itself, so instead of gtk.window_set_default_icon_name, it'll be gtk.Window.set_default_icon_name and gtk.Plug.new_from_display instead of gtk.plug_new_for_display

always register subclasses

Subclasses of GObject's would always be automatically registered, regardless of any __gtype_name__, __gproperties__, or __gsignals__ being defined on the class or not. Currently, classes don't get registered even when do_xxxx virtual methods are defined, which is bad.

revise registration properties/signals

the current __gproperties__ and __gsignals__ special class attributes containing dictionaries is practical but ugly and 1) difficult to extend 2) difficult to omit optional information. Kiwi2 is developing a better interface, with gproperty and gsignal utility functions. We should also support widget style properties.

revise properties dispatching

Having GObject properties always mapped to do_set_property and do_get_property forces the programmer to have each of those functions have a potentially large series of if name == 'foo': ... elif name == 'bar' ..., making the code ugly and slow, not to mention tedious to write. A better system would be something like either

• The native python object properties, where you can specify getter/setter methods. Example:

class Foo(gobject.GObject):
    def set_myprop(self, value): ...
    def get_myprop(self): return ...
    gobject.property("myprop", int, get_myprop, set_myprop)

• This is actually more explicit, and more pythonic since it's very similar to python's builtin property() function.

• Or, subst the property name in a method name template, then call that method, like do_set_foo, do_get_bar.

NO_IMPORT_PYGOBJECT

The current way gobject API is imported unless NO_IMPORT_PYGOBJECT is defined before #including <pygobject.h> causes lots of problems. It is very easy to forget this missing #define when #including <pygobject.h> from several sources that link to form the same module, causing bugs in some plaforms, like OS X (eg. gnomebug:315382). The solution: make it the reverse, #include <pygobject.h> should not import the API unless PYGOBJECT_IMPORT is defined.

Disable instance attributes (to improve garbage collection)

The ability to have instance attributes on arbitrary GObjects is vital for subclassing, but not that much important for builtin objects. And it comes with a cost. because of the instance dict, pygtk is forced to keep PyGObjects alive as long as the GObject is alive. Thus, it is forced to rely on the cyclic GC to free these objects. If we could disable the instance dict, then users would not be able to set arbitrary attributes on GObject instances, but on the other hand pygtk would be free to let a GObject wrapper to be freed and later recreated. This means that we don't need a reference from the GObject to the PyGObject, thus no reference cycle is created, so the PyGObjects and GObjects are freed as soon as possible. No more gc.collect(). Only for subclassed types we need to have the instance dictionary, but that represents a small fraction of all objects. PS: it should be possible to implement this even in pygtk 2.x, in a compatible way, by adding a PyDict  as qdata of the GObject, and redirecting PyGObject's tp_setattro/tp_getattro to the dictionary. Maybe even add a deprecation warning in this case. PS2: This is now being handled in gnomebug:320428.