Note: This article was first published the May 2008 issue of Python Magazine

Introducing Descriptors and Properties

Mark Mruss

New-style classes were introduced to Python with the release of Python 2.2. And with these new-style classes came descriptors and properties. This article will introduce the descriptor protocol, descriptors, and properties.

Introduction

New-style classes were introduced to Python with the release of Python 2.2. A new-style class is any class that is derived from the object base class. New-style classes give Python programmers many new (and initially confusing) features. One such feature is the descriptor protocol, and more specifically descriptors themselves.

Descriptors give Python programmers the ability to easily and efficiently create “managed attributes”. Managed attributes can be thought of as attributes that are not accessed directly. Instead their access is “managed” by something else, generally a class or a function.

If you haven’t come across this before you are probably wondering why one would want to manage attribute access? One reason might be that you don’t want people to be able to delete the attribute. Another reason may be that you need to ensure that your attribute data is always valid. Or perhaps attribute x is based on attribute y, so every time the value of y changes you want to update the value of x. From these few examples you can see the many possible cases where you might want to control access to certain attributes.

For those of you familiar with other programming languages, this type of access is often referred to as “getters and setters”. In many language, implementing “getters and setters” means using private variables and public functions that get and set the variable’s value. Since Python doesn’t (really) have private variables, the descriptor protocol is basically a built-in and “Python-ic” way to way to achieve something similar.

This article will introduce you to the descriptor protocol, descriptors, and properties. It will focus on demonstrating how to use them to create managed attributes. Since the descriptor protocol requires new-style classes, all of the examples in this article require Python 2.2 or newer.

A few definitions

Before moving forward, it is important to understand a few related terms. These terms will introduce some basic concepts and help you follow along with the remainder of the article.

descriptor protocol – The following three methods make up the descriptor protocol: __get__, __set__, and __delete__.

descriptor – An “object attribute with binding behavior, one whose attribute access has been overridden by methods in the descriptor protocol.” [1] In other words an “attributes whose usage resembles attribute access, but whose implementation uses method calls.”[2]

data descriptor – A descriptor with the __get__ and __set__ methods of the descriptor protocol defined.

non-data descriptor – A descriptor with only the __get__ method of the descriptor protocol defined. “Python methods (including staticmethod() and classmethod()) are implemented as non-data descriptors.” [3]

property – A built-in type that implements the descriptor protocol and allows you to easily create data descriptors.

Don’t worry if you don’t fully understand these definitions, the remainder of this article will hopefully clarify any confusion you have.

The Descriptor Protocol

Let’s take a closer look at the descriptor protocol and see how we can use it to create a descriptor. As previously mentioned, the descriptor protocol is made up of three methods: __get__, __set__, and __delete__. These methods have specific signatures and they are as follows, where self is the class that owns the methods:

__get__(self, instance, owner)
__set__(self, instance, value)
__delete__(self, instance)

These three methods represent the three basic operations that you perform on attributes in general: querying the value of that attribute; assigning a value to it; and, (very rarely) deleting it. They work as follows:

• The __get__ method is called when the attributes value is being queried. The __get__ method should return the (computed) attribute value or raise an AttributeError exception.” [4] This is where access to the attribute’s value is managed.
• The __set__ method is used in the assignment operation. It is called when we want to set the attribute value. This is where you can control what values, or types of values are being assigned to your attribute.
• Finally, the __delete__ method is called when we want to delete the attribute. Here you can (rarely) decide whether or not to delete the attribute.

There are also three different parameters passed to the three methods (excluding the standard self parameter for methods that belong to a class):

• owner – This “is always the owner class.” [5] This means that it is the actual class, and not an instance of the class. So if the descriptor is in a class called MyClass, owner will be that class.
• instance – An instance of class type owner. It is “the instance that the attribute was accessed through” [6], or None if the attribute is being accessed through the class (owner) instead of an instance.
• value- The value that the attribute is being set to.

This difference between owner and instance might be a bit confusing, so let’s look at a quick example. Let’s say we have a descriptor my_descriptor in the class MyClass, if we were to run the following code:

my_class_instance = MyClass()
print my_class_instance.my_descriptor

The second line queries the descriptors value and results in the __get__ method being called with the instance parameter being my_class_instance. The owner parameter will be the MyClass class.

Note: Notice that we treat the descriptor my_descriptor as though it is a normal attribute. We don’t call print my_class_instance.my_descriptor.__get__(my_class, MyClass). This is what was meant by: “attributes whose usage resembles attribute access, but whose implementation uses method calls.”[7]

If the following code were run:

print MyClass.my_descriptor

The __get__ method will again be called. This time the instance parameter will be None and the owner parameter will be the MyClass class.

Note: Only the __get__ method has the owner parameter. This means that it is the only function in the descriptor protocol that can be accessed through the class. Setting and deleting the descriptor through the class actually changes what the variable is. For example, if we tried to assign the numeric value 2 to a descriptor variable using the class, we would not access the descriptors __set__ method. Instead we would change the type of the variable from a descriptor to an integer with the value of 2.

A Simple Descriptor Example

A simple “transparent” descriptor example can be found in Listing 1. The first thing to notice in the code is that both the SimpleDescriptor and MyClass classes are “new-style” classes because they are derived from object. This is important because, as mentioned above, descriptors only work with “new-style” classes. The second point to notice is that the descriptor has class scope as opposed to instance scope. There are also two extra print statements included in the code. They are there to let us follow the execution a little more easily.

Listing 1

class SimpleDescriptor(object):

    def __get__(self, instance, owner):
        # Check if the value has been set
        if (not hasattr(self, "_value")):
            raise AttributeError
        print "Getting value: %s" % self._value
        return self._value

    def __set__(self, instance, value):
        print "Setting to %s" % value
        self._value = value

    def __delete__(self, instance):
        del(self._value)

class MyClass(object):
    my_value = SimpleDescriptor()

Using Listing 1 to execute the following code:

my_instance = MyClass()
my_instance.my_value = 416
print my_instance.my_value

The output would be the following:

Setting to 416
Getting value: 416
416

As you can see the second line (my_instance.data_descriptor = 416) calls the __set__ method and sets the _value attribute. When we call print my_instance.data_descriptor the __get__, method is called and the _value attribute is returned.

The Problem with the Simple Example

The previous example may look like a perfectly good descriptor, but there is something wrong with it. Take a look at what happens when we runs this new code:

my_instance = MyClass() #Create the first instance
my_instance.my_value = 416 #Set its' value
my_second_instance = MyClass() #Create the second instance
my_second_instance.my_value = 204 #Set its' value
print my_instance.my_value #What was the fist instance's value?

We get the following output:

Setting to 416
Setting to 204
Getting value: 204
204

Notice that when we set the second instance’s my_value descriptor to be 204, we are also setting the first instances. This is because my_value has class scope, so both instances (and the class itself) share the same instance of the SimpleDescriptor class. Since SimpleDescriptor only stores one value, they all actually share the same value. We will get the same results if we check what the classes value of my_value is:

my_instance = MyClass() #Create the first instance
my_instance.my_value = 416 #Set its' value
my_second_instance = MyClass() #Create the second instance
my_second_instance.my_value = 204 #Set its' value
print MyClass.my_value #What's the classes value?

We get the following results:

Setting to 416
Setting to 204
Getting value: 204
204

In the last line of the code (print MyClass.my_value #What's the classes value?) we simply use the class (ignoring both instances) in order to get the value of my_data. This will be an instance where the __get__ function will be called with the instance parameter set to None.

Note: This is not a problem if you want to share the value across all instances.

The Solution to the Problem

In order to get around this issue, you have to remember that if you want values unique to each instance your descriptors must store values that are unique to each instance. This can be in the instance itself, in dictionary in the descriptor, or perhaps in a text file. Just make sure that the value is unique to each instance. Though it seems like a simple solution, in practice a suitable solution for all cases is difficult to implement. As a result you should probably pick a specific implementation for your specific situations.

Using each instance as a key, one can store the value in a dictionary in the descriptor itself. The problem with this solution should be obvious to programmers familiar with Python dictionaries: only immutable types can be used as keys. This is fine if you know what object you are working with, but what about in the future when you want to add a descriptor to your sub-classed list?

Another solution is to store the value in the instance itself. You can do this by easily adding the value to the instance’s __dict__. The limitation is that the descriptor need to be given a suitable key so that there is no collision with anything already in the instance’s __dict__.

Listing 2 shows a solution to the problem from the previous section where the value is stored in the instance’s __dict__. Values are indexed using a key name provided during the creation of the descriptor. Aside from where we store the value, there is little difference between Listing 1 and Listing 2. Notice that the value name is a converted into a string. This is done to ensure that it can be used as a key.

Listing 2

class FixedDescriptor(object):

def __init__(self, value_name):
    self.value_name = str(value_name)

def __get__(self, instance, owner):
    if (instance is None):
        raise AttributeError
    elif (not instance.__dict__.has_key(self.value_name)):
        raise AttributeError
    return instance.__dict__[self.value_name]

    def __set__(self, instance, value):
        print "Setting to %s" % value
        instance.__dict__[self.value_name] = value

    def __delete__(self, instance):
        if (instance.__dict__.has_key(self.value_name)):
            del(instance.__dict__[self.value_name])


class MyClass(object):
    my_value = FixedDescriptor("__value")

The major usage difference between Listing 1 and Listing 2 is the fact that the __get__ method no longer works at class level; it only works at instance level. This should be obvious since this solution stores the value in the instance. If there is no instance, we have nowhere to store the value! If you attempt to access the descriptor at class level (the first if statement) an attribute error will be raised:

def __get__(self, instance, owner):
    if (instance is None):
        raise AttributeError
    elif (not instance.__dict__.has_key(self.value_name)):
        raise AttributeError
    return instance.__dict__[self.value_name]

Easy Data Descriptors with Properties

The descriptor provided in Listing 2 will work for many situations but for my money the easiest way to implement data descriptors is to use the property type. I would recommend using it unless you need the same descriptor across many different classes or attributes (i.e. for type validation). Properties can be thought of as a simple and easy way to create data descriptors. The property type implements the descriptor protocol and gets around the problem of where to store the descriptor value in an easy way: it lets the class that created the descriptor deal with it.

The full signature of the property function is as follows:

property(fget=None, fset=None, fdel=None, doc=None)

Where fget, fset, fdel are methods that will be called when the __get__, __set__, and __del__ members of the descriptor protocol are called. The doc parameter is a string that will be used as the docstring for the descriptor. If the doc parameter is not specified, the docstring of the fget method is used.

The signature of the fget, fset, fdel functions are as follows:

fget(instance)
fset(instance, value)
fdel(instance)

In the three signatures, instance is a reference to the object that owns the property attribute. This is the same instance that gets passed to the descriptor protocol. Since instance is the first parameter of each method, these are, for all intents and purposes, member methods of a class. The value parameter is the same as the value parameter that is passed to the __set__ method. It is what we are setting the attribute to.

The basic way to implement properties can be seen in Listing 3. As you can see, what we do for a property is very similar to what we did for our initial descriptor in Listing 1. We set up the three functions necessary for the descriptor protocol, and then use them to create our property attribute. Creating the property is very simple:

Listing 3

class MyClass(object):
    #Create the fget, fset, and fdel methods
    def __get_value(self):
        print "Getting value: %s" % self.__value
        return self.__value

    def __set_value(self, value):
        print "Setting to %s" % value
        self.__value = value

    def __del_value(self):
        del(self.__value)

    #Create the property
    my_value = property(__get_value
            , __set_value
            , __del_value
            , "This is my property")

    def __init__(self, value=0):
        self.my_value = value

my_value = property(__get_value
        , __set_value
        , __del_value
        , "This is my property")

Make Data Attributes Data-Descriptors

A common reason to use descriptors is to create read-only attributes. This means allowing callers to get (or access) an attribute’s value, but not allowing them to set its’ value. At first glance it seems as though one can accomplish this by using descriptors with only the __get__ method defined, i.e. a “non-data descriptor”.

While this seems to create a read-only descriptor attribute, it actually does nothing of the sort. Instead of using the descriptor’s __set__ function for the assignment operation (since no __set__ function is defined), the default Python assignment operation is used. This means that instead of stopping the assignment operation, a new attribute will be created in the instance (remember that descriptors have class scope) having the same name as the descriptor attribute and taking precedence in future operations.

This may be a bit confusing so let’s look at the example in Listing 4. It’s very much like our previous descriptor examples except it does not specify the __set__ and __del__ functions. Let’s look at what happens when we try to use this as though it were a read-only attribute:

Listing 4

class WonkyDescriptor(object):
    """This Descriptor isn't read only"""
    def __init__(self, value_name):
        self.value_name = str(value_name)

    def __get__(self, instance, owner):
        if (instance is None):
            raise AttributeError
        elif (not instance.__dict__.has_key(self.value_name)):
            raise AttributeError
        print "Getting a value"
        return instance.__dict__[self.value_name]

class MyClass(object):

    my_value = WonkyDescriptor("_value")

    def __init__(self, value):
        #initial value
        self._value = value

my_instance = MyClass(23) #Create the first instance
print my_instance.my_value
my_instance.my_value = "Don't set me!"
print my_instance.my_value

When we run this, we get the following output:

Getting a value
23
Don't set me!

As you can see we did not succeed in creating a read-only attribute, instead something else happened. The “Getting a value” string is printed out when we print out my_value for the first time. This means that we are accessing the value through the descriptor. We then set the value of the descriptor attribute and print out that new value. Since “Getting a value” isn’t printed out a second time, we know that the descriptor’s __get__ method is not accessed when the second print statement is called.

Let’s take a closer look at what is happening using the following code, which prints out the instance’s __dict__:

my_instance = MyClass(23) #Create the first instance
print my_instance.__dict__
my_instance.my_value = "Don't set me!"
print my_instance.__dict__

This results in the following, which explains what is happening:

{'_value': 23}
{'_value': 23, 'my_value': "Don't set me!"}

When we first access the __dict__ we see our value indexed by the _value key that we told the descriptor to use. Now look at the second __dict__. The old value is still there, but so is a new value my_value. When we assigned “Don’t set me!” to my_value, we didn’t overwrite the descriptor attribute at class scope, we created a new instance attribute! And it is not exactly a read-only attribute.

In order to create a read-only attribute, you need to create a data descriptor where the __set__ method raises an AttributeError exception. An easy way to do this is to create a property and only set the fget function. Instead of using the descriptor in Listing 4, we can construct a read-only attribute as follows:

def __get_value(self):
    return self._value
my_value = property(__get_value)

Conclusion

I hope that after reading this article you can see how powerful descriptors (especially data-descriptors) can be. Once you get the hang of them, they are a great way to implement “getters and setters” and read-only attributes. Data-Descriptors are also very useful for performing validation during the assignment operation, i.e. ensuring that a value remains a specific type, or in a specific form.

The more you play with descriptors and use them in your code, the more you’ll see how sophisticated and useful they can be. That being said, it’s important to remember that unless you have a good reason to use descriptors you probably don’t need them. There’s no need to sacrifice the readability of your code or the dynamism of Python just for the sake of using descriptors. But when you have a real reason for managed attributes, you’ll find that descriptors are more than up to the task.

[1] http://docs.python.org/ref/descriptor-invocation.html
[2] http://www.python.org/download/releases/2.2/descrintro/#property
[3] http://docs.python.org/ref/descriptor-invocation.html
[4] http://docs.python.org/ref/descriptors.html
[5] http://docs.python.org/ref/descriptors.html
[6] http://docs.python.org/ref/descriptors.html
[7] http://www.python.org/download/releases/2.2/descrintro/#property

Note: This article was first published the April 2008 issue of Python Magazine

By: Mark Mruss

GUI programming, like many other types of programming, can sometimes prove exhausting because you must repeat yourself over and over again. AVC is one tool available to Python GUI programmers that attempts to simplify things by synchronizing application data and GUI widgets.

Introduction

Every once in a while I find myself browsing the Internet trying to find out what’s new and exciting in the Python world. Sometimes I browse to find topics for this article; other times mere curiosity draws me across the web. While I was browsing the other day, I stumbled across AVC: the Application View Controller [1]. I was immediately intrigued by it because its’ name is so similar to the Model View Controller (MVC) pattern. Being familiar with the Model View Controller pattern, and admittedly having struggles with it in the past, I decided to check out AVC to determine if it might be a viable alternative.

After reading about AVC I was intrigued for several reasons. The main reason was the promise of “a multiplatform, fully automatic, live connection among graphical interface widgets and application variables.” [2] This means that graphical widgets can be connected to variables and automatically synchronized. One of the (many?) problems with Graphical User Interface (GUI) programming is that you often find yourself doing the same thing over and over again. One of the things that you end of doing over and over again is setting the contents of a widget based on the value of a variable, and then subsequently, setting that variable’s value based on the current state of the widget. Whenever someone promises me an automatic connection between GUI widgets and my variables, I’m interested.

The other reason for investigating AVC is my past struggles with the Model View Controller pattern. I like the decoupling that the MVC pattern seems to provide, but I often feel as though I am needlessly duplicating code in order to stick with the pattern. I looked into AVC hoping to find a simple framework that will avoid this and guide the separation of my application data from my GUI logic. However in the end, I realized that AVC (in its current state), does not appear to achieve this across all widget toolkits. It does allow you to separate your application from much of the GUI logic that one would normally need, but it does not appear to allow you to fully separate the data from the GUI.

AVC is being developed by Fabrizio Pollastri, and is released under version 3 of the GPL. I was unable to find much information about the project’s future or design objectives. But judging by the release notes, it is still being actively developed. The project is only at version 0.5 so don’t be surprised if the API (Application Programming Interface) or some of the goals change. Although relatively new, AVC bears further investigation because it already simplifies your GUI programming and contains the potential to do much more. In this article, I will introduce some of the main concepts behind AVC, and provide a small, working example using AVC and PyGTK.

Installing AVC

AVC is a “Python module written in pure python” [3]. This means that AVC is easy to install and does not have any dependencies aside from Python 2.2 or greater. You can download the current version (0.5.0) from the website or, if you are a lucky Linux user like me, you can install via your handy package manger. If you download the source, you can install it after extraction, using the following command:

python setup.py install

Depending on which widget toolkit you plan on using, the following requirements must also be met:

• GTK+: PyGTK 2.8 – 2.10
• Qt: PyQt or PyQt4v3 – v4
• Tk: Tkinter 2.4
• wxWidgets: wxPython 2.6

You can easily install any of the above toolkits using your favourite package manager, a source archive, or a binary installer found on each toolkit’s main website. Once AVC is installed, you can test the installation by importing the avc module from the interactive interpreter. If all goes well you will see something similar to the following:

$ python
Python 2.4.4 (#2, Jan  3 2008, 13:36:28)
[GCC 4.2.3 20071123 (prerelease) (Debian 4.2.2-4)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import avc
>>>

Widget Support

In its current state, AVC does not support all widgets available across all toolkits. It does currently support the following widgets:

• Button
• Check Box
• Combo Box (Not supported in Tk)
• Entry
• Label
• Radio Button
• Slider
• Spin Button
• Status Bar (Only supported by GTK+ and wxWidgets)
• Text View
• Toggle Button.

The support of each of these widget types is then handled by specific widgets in each toolkit.

Name-Matching

In order to automatically synchronize variables and GUI widgets, AVC uses a name-matching technique. AVC supports two methods of name matching. The first method requires that the variable and the widget have the same name. For example, if you have a variable named my_data it will match with a widget also named my_data. In other words, if a variable and a widget have the same name they will be connected and their values synchronized.

The second name-matching technique allows you to connect variables to one or more widgets. Widgets can only be connected to one variable, but variables can be connected to any number of widgets. Using the second name-matching technique, you have a match if the widget name contains a double-underscore (__), and the portion before the double-underscore matches the variable name. For example, if you have variable named my_numeric_value and you want to match it with a Label widget and an Entry widget, you do this by naming the widgets as follows:

my_numeric_value__label
my_numeric_value__entry

Again, the text before the “__” must match the variable name, and the text after the “__” can be whatever you want to differentiate your widgets or ensure uniqueness (if the toolkit requires it).

A GTK+, PyGTK, and AVC Example

For this AVC example, I will use the GTK+ widget toolkit and PyGTK. PyGTK a “is a set of bindings to the GTK+ user interface toolkit for the Python language” [4]. This means that it lets us write GUI applications in Python using the GTK+ widget toolkit. To avoid any flame wars: I did not choose GTK+ because it is the best toolkit but because it is the toolkit with which I am the most familiar. In order to run this example you will need to have PyGTK 2.8 or later installed. You can get the latest version of PyGTK from the PyGTK website. [5]

As I mentioned earlier, AVC works with many different widgets types. It also has many different features. I won’t be covering all of the features or widgets types in this column; if you are interesting in learning about some of these features or how to work with different widgets types, please see the AVC documentation. [6]

This example is relatively simple, but it should illustrate some of the basic features of AVC. The example application asks for a person’s name and then displays that name in pop-up dialog. It will have the following features:

1. A gtk.TextView widget to display the person’s name and allow the name to be edited. The gtk.TextView widget will be synchronised with a variable.
2. A gtkButton that will pop-up a gtk.MessageDialog to show the person’s name.
3. A gtk.Button that will reset the name to the name with which the application was initialized.

To begin we need to import all of the modules necessary:

import gtk
import avc.avcgtk

Note: I am using a gtk.TextView widget instead of a gtk.Entry widget. In its current state, AVC does not propagate changes in gtk.Entry widgets back to the connected variable. I’m not sure if this is a current limitation or part of the design.

The above code imports the PyGTK module necessary to work with GTK+. It also imports the avcgtk module, which is used to link our “application variables” with our GTK+ GUI. Depending on what widget toolkit you use, you will have to use different modules. For example, if you are working with Qt4, you will import:

import avc.avcqt4

The next step is to create the “application” class. This will be the class that contains the data. In this example it will also create the GUI:

class gtkAVC(avc.avcgtk.AVC):

Notice that we derive our application from the avcgtk module’s AVC class. This is the GTK+ specific AVC class with which we will work. We will also create an __init__ method in the gtkAVC class. This is where we will initialize the data that will be connected to the GUI and create the GUI via the init_gui method:

def __init__(self, name=""):
    #set the variable and save the initial name
    self.initial_name = name
    self.name = name
    #setup GUI
    self.init_gui()

What we have here is pretty simple. We have the optional parameter name that we store as the current name and as the initial name. We then call the init_gui method that will create the GUI. The contents of the init_gui method can be seen in Listing 1. I won’t explain most of this code since the majority of it is PyGTK specific. However I will make note of several relevant segments below.

Listing 1

def init_gui(self):

    #Setup the window and the layout manager
    self.window = gtk.Window()
    self.window.connect("destroy", gtk.main_quit)

    self.h_layout = gtk.HBox()
    self.window.add(self.h_layout)

    #create the widgets
    self.text_label = gtk.Label("Say hello:")
    self.h_layout.add(self.text_label)

    self.frame = gtk.Frame()
    self.h_layout.add(self.frame)
    self.scrolled_window = gtk.ScrolledWindow()
    self.frame.add(self.scrolled_window)

    self.text_view = gtk.TextView()
    self.text_view.set_name("name__text_view")
    self.scrolled_window.add(self.text_view)

    self.hello_button = gtk.Button("Hello!")
    self.hello_button.connect("clicked", self.on_hello_clicked)
    self.h_layout.add(self.hello_button)

    self.reset_button = gtk.Button("Reset")
    self.reset_button.connect("clicked", self.on_reset_clicked)
    self.h_layout.add(self.reset_button)

    self.window.show_all()

The only AVC specific code segment in the init_gui function is where we set the name of the gtk.TextView widget:

self.text_view.set_name("name__text_view")

This is all the code that we need to connect the gtk.TextView widget with the name variable that we created at the beginning of the __init__ function. (Now, how’s that for simple?) Notice that the name section of the “name__text_view” string will match with the self.name variable. It is also important to note that the variable and the widget are not yet connected. They will become connected when the avc_init method is called.

The other non-AVC related code of note is the connection of both gtk.Button widgets’ clicked signals with signal handlers. We connect the “hello” button to the on_hello_clicked method and the “reset” button to the on_reset_clicked method.

That’s it for the init_gui function, now let’s look at the two signal handlers. The on_hello_clicked method, shown in Listing 2, simply displays the name in a gtk.MessageDialog. What should be interesting to GUI programmers about this function is that instead of reading the data from the gtk.TextView widget, we simply reference self.name for the dialog’s text. We can do this because self.name and the gtk.TextView widget are connected and their values are always the same.

Listing 2

def on_hello_clicked(self, widget):
    def close(dialog, response):
        #Close the dialog on ok
        dialog.destroy()
    message_dlg = gtk.MessageDialog(self.window
        , 0
        , gtk.MESSAGE_INFO
        , gtk.BUTTONS_OK
        , ("Hello: %s" % self.name))
    message_dlg.connect("response", close)
    message_dlg.run()

The on_reset_clicked function is also very simple and straightforward. We simply reset the name to the initial name:

def on_reset_clicked(self, widget):
    #Reset the name to the initial name
    self.name = self.initial_name

Again, notice that we don’t have to worry about doing anything to the gtk.TextView widget that displays the current name. By simply modifying the data, what is displayed in the GUI will automatically be updated by AVC.

The next and final step in our test application is to create our class instances and actually show the GUI:

if (__name__ == "__main__"):
    gtk_avc = gtkAVC("Mark Mruss")
    gtk_avc.avc_init()
    gtk.main()

Since I am working in a Python file, I perform a simple test to make sure that the file is being launched directly instead of being imported as a module. I then create an instance of the gtkAVC class setting the name to be my name. The avc_init method is then called (which is a member of the avc.avcgtk.AVC class). The avc_init method is where all of the magic happens. It is where AVC goes through an application’s variables and connects them to the GUI widgets based upon the name matching technique explained earlier. avc_init must be called after all of the data in the “application” and the widgets have been created.

The final step in this example, is to run the gtk.main function. This is the “main loop” of our PyGTK based application and is standard when working with PyGTK.

The entire code can be seen in Listing 3. When you run the code you will be greeted with something similar to Figure 1. It may not seem like much, but what we have here is a fully functional AVC “application”. This simple “application” illustrates how easy it is to create an automatic connection between your data and your GUI.

Figure1

Listing 3

#! /usr/bin/env python
import gtk
import avc.avcgtk

class gtkAVC(avc.avcgtk.AVC):

    def __init__(self, name=""):
        #set the variable and save the initial name
        self.initial_name = name
        self.name = name
        #setup GUI
        self.init_gui()

    def init_gui(self):

        #Setup the window and the layout manager
        self.window = gtk.Window()
        self.window.connect("destroy", gtk.main_quit)

        self.h_layout = gtk.HBox()
        self.window.add(self.h_layout)

        #create the widgets
        self.text_label = gtk.Label("Say hello:")
        self.h_layout.add(self.text_label)

        self.frame = gtk.Frame()
        self.h_layout.add(self.frame)
        self.scrolled_window = gtk.ScrolledWindow()
        self.frame.add(self.scrolled_window)

        self.text_view = gtk.TextView()
        self.text_view.set_name("name__text_view")
        self.scrolled_window.add(self.text_view)

        self.hello_button = gtk.Button("Hello!")
        self.hello_button.connect("clicked", self.on_hello_clicked)
        self.h_layout.add(self.hello_button)

        self.reset_button = gtk.Button("Reset")
        self.reset_button.connect("clicked", self.on_reset_clicked)
        self.h_layout.add(self.reset_button)

        self.window.show_all()

    def on_hello_clicked(self, widget):
        def close(dialog, response):
            #Close the dialog on ok
            dialog.destroy()
        message_dlg = gtk.MessageDialog(self.window
            , 0
            , gtk.MESSAGE_INFO
            , gtk.BUTTONS_OK
            , ("Hello: %s" % self.name))
        message_dlg.connect("response", close)
        message_dlg.run()

    def on_reset_clicked(self, widget):
        #Reset the name to the initial name
        self.name = self.initial_name

if (__name__ == "__main__"):
    gtk_avc = gtkAVC("Mark Mruss")
    gtk_avc.avc_init()
    gtk.main()

Benefits and Limitations

For a project that is little more than one year old (the first release was in January 2007) AVC appears quite stable and ready to be used. This is not to say that AVC is perfect. I did encounter a few issues.

The most notable issue that I encountered is the tightly coupled structure that AVC seems to impose on your application. For a module that tries to simplify the relationship between application data and GUI’s, this feels like a bit of an issue because. For example, when testing using PyGTK I was able to easily separate the GUI and the “application” into separate classes. But when I tried to do the same thing using PyQt4, I encountered an error because the avc_timer function in the avc.avcqt4.AVC module expects that the “application” class is itself a QObject (namely the actual QApplication). I find this counterintuitive since being able to separate the data from the GUI-logic seems to be a goal of AVC and similar tools. If you are able to separate the “application” fully from the GUI, you can easily connect your “application” to different GUI’s, and (by changing the AVC base class) even different widget toolkits.

I would also be interested in the ability to connect more types of data to more types of widgets. For example, I am interested in synchronizing Python lists with the contents of List boxes and Combo boxes. This is in addition to the current ability to synchronize the selection in the two widgets with integers.

Of course AVC also has a lot going for it. For one, I really like that AVC works with different widget toolkits. I have not seen this very often. It is a real benefit, especially when it comes to people adopting AVC. Hopefully in the future AVC will allow for further separation of the data and the GUI, truly enabling us to use different GUI’s and different widget toolkits with our data.

What I like most about AVC is its simplicity. I have played around with similar solutions and AVC is one of the leaders in terms of ease of use. I was able to get create a simple AVC based application in almost no time at all. (The time that it did take was spent trying to remember PyGTK.) Much of this has to do with the streamlined nature of AVC. There is very little to configure regardless of what widget toolkit you use. While this simplicity limits what AVC can currently achieve compared to other solutions, it also makes the barrier to entry low and the usage trivial. User friendliness is certainly a good thing in a package that aims to make GUI application development easier.

Conclusion

While the data that we worked with in the earlier example wasn’t that complicated (a simple string), I hope that it illustrates how helpful AVC is if you are working with a large amount of data or data that could be updated by an external source. Instead of having to worry about what widgets or toolkits the data was being displayed in, AVC lets us work with the data and GUI transparently, leaving the synchronization to AVC.

If what AVC offers sounds interesting to you, download it from the AVC website and try it out. Although it it’s not there just yet with enough attention, usage, and contributions from the Python community, AVC should reach full-feature status in no time.

[1] http://avc.inrim.it/html/
[2] http://avc.inrim.it/html/
[3] http://avc.inrim.it/html/
[4] http://faq.pygtk.org/index.py?req=all#1.1
[5] http://www.pygtk.org/downloads.html
[6] http://avc.inrim.it/doc/user_manual.pdf

Note: If you haven’t already, please check out my Python version poll.

Mark Mruss

Note: This article was first published the October 2007 issue of Python Magazine

XML is everywhere. It seems you can’t do much these days unless you utilize XML in one way or another. Fortunately, Python developers have a new tool in our standard arsenal: the ElementTree module. This article aims to introduce you to reading, writing, saving, and loading XML using the ElementTree module.

1. Introduction
2. Reading XML data
3. Listing 1
4. Listing 2
5. Reading XML Attributes
6. Writing XML
7. Listing 3
8. Writing XML Attributes
9. Reading XML Files
10. Writing XML Data to a File
11. Reading from the Web
12. Conclusion

Introduction

It seems like everyone needs to parse XML these days. They’re either saving their own information in XML or loading in someone else’s data. This is why I was glad to learn that as of Python 2.5, the ElementTree XML package has been added to the standard library in the XML module.

What I like about the ElementTree module is that it just seems to make sense. This might seem like a strange thing to say about an XML module, but I’ve had to parse enough XML in my time to know that if an XML module makes sense the first time you use it, it’s probably a keeper. The ElementTree module allows me to work with XML data in a way that is similar to how I think about XML data.

A subset of the full ElementTree module is available in the Python 2.5 standard library as xml.etree, but you don’t have to use Python 2.5 in order to use the ElementTree module. If you are still using an older version of Python (1.5.2 or later) you can simply download the module from its website and manually install it on your system. The website also has very easy to follow installation instructions, which you should consult to avoid issues while installing ElementTree.

In general, the ElementTree module treats XML data as a list of lists. All XML has a root element that will have zero or more subelements (or child elements). Each of those subelements may in turn have subelements of their own. The best way to think about this is with a brief example.

First let’s take a look at some sample XML data:

<root>
<child>One</child>
<child>Two</child>
</root>

Here we have a root element with two child elements. Each child element has some text associated with it seen here as “one” and “two”. If we examine the XML as a hierarchical list of lists we see that we have one element “root” in our root list. Within the “root” element we have a list containing two subelements “child” and “child”. The two “child” elements would then contain empty lists representing their lack of subelements. Not too complicated so far, is it?

Reading XML data

Now let’s use the ElementTree package to parse this XML and print the text data associated with each child element. To start, we’ll create a Python file with the contents shown in Listing 1.

Listing 1

#!/usr/bin/env python

def main():
	pass

if __name__ == "__main__":
	main()

This is basically a template that I use for many of my simple “*.py” files. It doesn’t actually do anything except set up the script so that when the file is run, the main method will be executed. Some people like to use the Python interactive interpreter for simple hacking like this. Personally, I prefer having my code stored in a handy file so I can make simple changes and re-run the entire script when I am just playing around.

The first thing that we need to do in our Python code is import the ElementTree module:

from xml.etree import ElementTree as ET

Note: If you are not using Python 2.5 and have installed the ElementTree module on your own, you should import the ElementTree module as follows:

from elementtree import ElementTree as ET

This will import the ElementTree section of the module into your program aliased as ET. However, you don’t have to import ElementTree using an alias; you can simply import it and access it as ElementTree. Using ET is demonstrated in the Python 2.5 “What’s new” documentation[1] and I think it’s a great way to eliminate some key strokes.

Now we’ll begin writing code in the main method. The first step is to load the XML data described above. Normally you will be working with a file or URL; for now we want to keep this simple and load the XML data directly from the text:

element = ET.XML(
       "<root><child>One</child><child>Two</child></root>")

The XML function is described in the ElementTree documentation as follows: “Parses an XML document from a string constant. This function can be used to embed “XML literals” in Python code”[2].

Be careful here! The XML function returns an Element object, and not an ElementTree object as one might expect. Element objects are used to represent XML elements, whereas the ElementTree object is used to represent the entire XML document. Element objects may represent the entire XML document if they are the root element but will not if they are a subelement. ElementTree objects also add “some extra support for serialization to and from standard XML.”[3] The Element object that is returned represents the element in our XML data.

Thankfully, the Element object is an iterator object so we can use a for loop to loop through all of its child elements:

for subelement in element:

This will give us all the child elements in the root element. As mentioned earlier, each element in the XML tree is represented as an Element object, so as we iterate through the root element’s child elements we are getting Element objects with which to work. Meaning that each loop though the for loop will give us the next child element in the form of an Element object until there are no more children left. In order to print out the text associated with an Element object we simply have to access the Element object’s text attribute:

for subelement in element:
       print subelement.text

To recap, have a look at the code in Listing 2.

Listing 2

#!/usr/bin/env python

from xml.etree import ElementTree as ET

def main():
	element = ET.XML("<root><child>One</child><child>Two</child></root>")
	for subelement in element:
		print subelement.text

if __name__ == "__main__":
	# Someone is launching this directly
	main()

Once you run the code you should get the following output:

One
Two

If an XML element does not have any text associated with it, like our root element, the Element object’s text attribute will be set to None. If you want to check if an element had any text associated with it, you can do the following:

if element.text is not None:
       print element.text

Reading XML Attributes

Let’s alter the XML that we are working with to add attributes to the elements and look at how we would parse that information.

If the XML uses attributes in addition to, or instead of, inner text they can be accessed using the Element object’s attrib attribute. The attrib attribute is a Python dictionary and is relatively easy to use:

def main():
       element = ET.XML(
               '<root><child val="One"/><child val="Two"/></root>')
       for subelement in element:
               print subelement.attrib

When you run the code you get the following output:

{'val': 'One'}
{'val': 'Two'}

These are the attributes for each child element stored in a dictionary. Being able to work with an XML element’s attributes as a Python dictionary is a great feature and fits well with the dynamic nature of XML attributes.

Writing XML

Now that we’ve tried our hand at reading XML, let’s try creating some. If you understand the reading process, you should have no trouble understanding the creation process because it works in much the same manner. What we are going to do in this example is recreate the XML data that we were working with above.

The first step is to create our element:

#create the root <root>
root_element = ET.Element("root")

After this code is executed, the variable root_element is an Element object, just like the Element objects that we used earlier to parse the XML.

The next step is to create the two child elements. There are two ways to do this.

In the first method, if you know exactly what you are creating, it’s easiest to use the SubElement method, which creates an Element object that is a subelement (or child) of another Element object:

#create the first child <child>One</child>
child = ET.SubElement(root_element, "child")

This will create a Element that is a child of root_element. We then need to set the text associated with that element. To do this we use the same text attribute that we used in the first parsing example. However, instead of simply reading the text attribute we set its value:

child.text = "One"

The second approach to creating a child element is to create an Element object separately (rather than a sub element) and append it to a parent Element object. The results are exactly the same – this is simply a different approach that may come in handy when creating your XML,or working with two sets of XML data.

First we create an Element object in the same way that we created the root element:

#create the second child <child>Two</child>
child = ET.Element("child")
child.text = "Two"

This creates the child Element object and sets its text to “Two”. We then append it to the root element:

#now append
root_element.append(child)

Pretty simple! Now, if we want to look at the contents of our root_element (or any other Element object for that matter) we can use the handy tostring function. It does exactly what it says that it does: it converts an Element object into a human readable string.

#Let's see the results
print ET.tostring(root_element)

Listing 3

#!/usr/bin/env python

from xml.etree import ElementTree as ET

def main():
	#create the root </root><root>
	root_element = ET.Element("root")
	#create the first child <child>One</child>
	child = ET.SubElement(root_element, "child")
	child.text = "One"
	#create the second child <child>Two</child>
	child = ET.Element("child")
	child.text = "Two"
	#now append
	root_element.append(child)
	#Let's see the results
	print ET.tostring(root_element)

if __name__ == "__main__":
	# Someone is launching this directly
	main()

To recap, have a look at the code in Listing 3. When you run this code you will get the following output:

</root><root><child>One</child><child>Two</child></root>

Writing XML Attributes

If you want to create the XML with attributes (as illustrated in the second reading example), you can use the Element object’s set method. To add the val attribute to the first element, use the following:

child.set("val","One")

You may also set attributes when you create Element objects:

child = ET.Element("child", val="One")

Reading XML Files

Most of the time you won’t be working with XML data that you explicitly create in your code, instead you will usually read the XML data in from a data source, work with it, and then save it back out when you are done. Fortunately, configuring ElementTree to work with different data sources is very easy. For example, let’s take the XML data that we first used and save it into a file named our.xml in the same location as our Python file.

There are a few methods that we can use to load XML data from a file. We are going to use the parse function. This function is nice because it will accept, as a parameter, the path to a file OR a “file-like” object. The term “file-like” is used on purpose because the object does not have to be a file object per se – it simply has to be an object that behaves in a file-like manner. A “file-like” object is an object that implements a “file-like” interface, meaning that it shares many (if not all) methods with the file object. If an object is “file-like” this fact will usually be prominently mentioned in its documentation.

The first thing that we need in order to load the XML data is determine the full path to the our.xml file. In order to calculate this, we determine the full path of our Python source file, strip the filename from it, and then append our.xml to the path. This is rather simple given that the __file__ attribute (available in Python 2.2 and later) is the relative path and filename of our Python source file. Although the __file__ attribute will be a relative path, we can use it to calculate the absolute path using the standard os module:

import os

We then call the abspath function to get the absolute path:

xml_file = os.path.abspath(__file__)

However, since we only want the directory name (not the full path and filename of our Python source file) we have to strip off the filename:

xml_file = os.path.dirname(xml_file)

Now that we have the directory in which the our.xml file resides, all we have to do is append the our.xml filename to the xml_file variable. However, instead of just doing something like:

xml_file += "/our.xml"

we will use the os module to join the two paths so that the resulting path is always correct regardless of what operating system our code is executed on:

xml_file = os.path.join(xml_file, "our.xml")

Note: If you have any trouble understanding what any of the code used to determine the path of our.xml is doing, try printing out xml_file after each of the above lines and it should become clear.

We now have the full path to the our.xml file. In order to load its XML data we simply pass the path to the parse function:

tree = ET.parse(xml_file)

We now have an ElementTree object instance that represents our XML file.

Since we are working with files, we should watch out for incorrect paths, I/O errors, or the parse function failing for any other reason. If you wish to be extra careful, you can wrap the parse function in a try/except block in order to catch any exceptions that may be thrown:

try:
       tree = ET.parse("sar")
except Exception, inst:
       print "Unexpected error opening %s: %s" % (xml_file, inst)
       return

In the except block, I catch the Exception base class so that I catch any and all exceptions that may be thrown (in the case of a missing file it will most likely be an IOError exception).

Writing XML Data to a File

Now that we know how to read in XML data, we should look at how one writes XML data out to a file. Let’s assume that after reading in the out.xml fiie we want to add another item to the XML file that we just read in:

child = ET.SubElement(tree.getroot(), "child")
child.text = "Three"

Notice that in order to add a child to the root element we used the ElementTree object’s getroot function. The getroot function simply returns the root Element object of the XML data.

Now that we have a third child element, let’s write the XML data back out to our.xml. Thanks to ElementTree this is a painless experience:

tree.write(xml_file)

That’s it!

If we want to be really careful when writing the XML data out to a file, we’ll watch out for exceptions. However most of the time the write method will succeed without throwing an exception; it is more important to be sure that the path used is correct. Often times, instead of getting the exception that you want, you end up with an XML file stored in some far off and strange location on your hard drive because your path was incorrect or you did not specify the full path. But, as is often the case when programming, better safe than sorry:

try:
       tree.write(xml_file)
except Exception, inst:
       print "Unexpected error writing to file %s: %s" % (xml_file, inst)
       return

To recap you can find all of the code from this section in Listing 4.

Listing 4

#!/usr/bin/env python

from xml.etree import ElementTree as ET
import os

def main():

	xml_file = os.path.abspath(__file__)
	xml_file = os.path.dirname(xml_file)
	xml_file = os.path.join(xml_file, "our.xml")

	try:
		tree = ET.parse(xml_file)
	except Exception, inst:
		print "Unexpected error opening %s: %s" % (xml_file, inst)
		return

	child = ET.SubElement(tree.getroot(), "child")
	child.text = "Three"

	try:
		tree.write(xml_file)
	except Exception, inst:
		print "Unexpected error writing to file %s: %s" % (xml_file, inst)
		return

if __name__ == "__main__":
	# Someone is launching this directly
	main()

When you run the code and take a look at the our.xml file you should see that the the third child element has been added:

<root>
<child>One</child>
<child>Two</child>
<child>Three</child>
</root>

Reading from the Web

Working with a local file is very useful, but you might also be in a situation where you will have to work with an XML file that is located on the Internet, perhaps an RSS feed. Fortunately, since the parse function explained above works with file-like elements, loading a URL is very easy.

First off, you need to import the urllib module; a standard module that allows you to open URLs in a method similar to opening local files:

import urllib

In order to open a URL we use:

feed = urllib.urlopen("http://pythonmagazine.com/c/news/atom")
tree = ET.parse(feed)

Conclusion

And that’s that! This concludes our brief introduction to XML parsing using the ElementTree module. Hopefully throughout this article you have seen how easy it is to create and manipulate XML using ElementTree …and I’ve only scratched the surface. For more information take a look at the official Python documentation and some of the great examples on the effbot website. I’m sure you’ll be an XML wizard in no time.

[1] http://docs.python.org/whatsnew/modules.html#SECTION0001420000000000000000
[2] http://effbot.org/zone/pythondoc-elementtree-ElementTree.htm#elementtree.ElementTree.XML-function
[3] http://effbot.org/zone/pythondoc-elementtree-ElementTree.htm#elementtree.ElementTree.ElementTree-class

So I had some free time since I last posted so I hacked a little bit more into my simple game editor. I’ve a few things in there that I wanted to get in:

• A grid
• A paint mode to easily add sprites
• An erase mode so that sprites can be removed
• Fully (or so it seems) working property addition to the sprites
• Added some organization to the code. I was hacking on this enough that putting things in their right spot started to make more and more sense.
• Started to use mercurial to keep track of source changes. I know how important version control is, and after making a silly mistake I decided that I wanted to start using it with this project.

You can take a look at how things are working here:

It’s not pretty yet, but it’s coming along.

Hey Everyone,

Sorry I’ve been away for a bit, work and trips and writing for Python Magazine had me pretty busy and I wasn’t able to reply to everyone’s comments on the simple Python game engine. I really do appreciate the comments though so please keep them coming.

I have been thinking about the simple game engine quite a bit though and wondering where to start on it all, and whether or not it makes sense to start on it at all! After some thinking I decided that what I would want most (for a variety of reasons) would be an easy to use level editor. So with a day off from work and life yesterday I started to do some hacking with PyGTK and pyglet to see if I couldn’t get a simple level editor going.

The results are still quite crude, but the basics are starting to get in there:

As you can see it’s a PyGTK application with an OpenGL window that displays pyglet sprites. There is a properties list, where you can add and edit properties or the sprite. There is also a “content” list that displays all of the graphics in your project’s “content” directory. Then you can add any of those images to your level. You can also select sprites and move them around, or edit their properties (notice the monster with the yellow border around it?).

The idea is that eventually this will save the information out into a human readable file type (yaml, xml, whatever) that games (your game?) will then read in for their levels. The properties will be saved with each sprite and then applied when you load the level. That way you can add specific properties to specific sprites.

This is still very much a work in progress, but when it gets a little bit more stable and if people are interested I think I’ll create a project on sourceforge or google code so the other people can start working with it or hacking it.

So…ideas? Comments? Thoughts?

No I’m not dead…even after the recent car accident….I’ve just been busy. Busy writing for columns for the monthly Python Magazine. But that does not mean that his blog is dead! In fact I’ve been spending the last hour looking around the web for something new and cool in the world of Python.

I’m looking for something new to sink my teeth into, something different. I’m looking forward to Python 3000, I’ve been trying to keep up with many of the changes and so far it’s looking really good. But in the mean time there must be something happening in the far off corners of the Python world…where someone is doing something extremely cool.

Please if you have an idea let me know, send me an email, or add a comment to this post. Is there anything that you want me to cover here? A tutorial that you would like? A tutorial that you have written? A new module you wrote? Whatever it is let me know! A new visualization tool? More Python on the web?

I’ve been spending too much time in the world of C++ lately and I’m hungry for some Python…

For this tutorial I’m going to take a look at PyGlet: “a cross-platform windowing and multimedia library for Python.” The reason that I decided to take a look at PyGlet is because it is an alternative to PyGame in the Python gaming world and: “No external dependencies or installation requirements. For most application and game requirements, pyglet needs nothing else besides Python, simplifying distribution and installation.”[1]

The first step to using PyGlet is to actually download it and install it (http://pyglet.org/download.html) as of writing this PyGlet is at version 1.0 alpha 2 (as I finished this tutorial Beta 1 was released but I have been unable to try it out), so between now and the final release there are bound to be a few changes. Once you have download the correct version for your system install it an you are ready to go. I’m writing this on a Debian box so I downloaded the source distribution and installed it using the following, as per the instructions:


python setup.py install


Now like PyGame, PyGlet is a framework for developing games or other applications, it is not a game engine, therefore if you are looking to create a full game you will need to create your own, or use someone else’s. This tutorial will not going into full game creation, instead it will introduce PyGlet using a small sample application, hopefully giving you enough of the basics, or enough of a taste to continue on with it.

You can download the full source to this tutorial here.

Creating a Window

The first step is to get an actual window displaying. In this initial code I’m going to create a window with a main game loop and display the Frames Per Second that the game is currently running at. In order to do this I am going to subclass from the pyglet.window.Window class. You don’t have to do this in order to display a window, but given the way that events are handled this seemed to make the most sense to me.

I added the following to a file named “PyGletSpace.py”

from pyglet import window
from pyglet import clock
from pyglet import font

class SpaceGameWindow(window.Window):

	def __init__(self, *args, **kwargs):

		#Let all of the standard stuff pass through
		window.Window.__init__(self, *args, **kwargs)

	def main_loop(self):

		#Create a font for our FPS clock
		ft = font.load('Arial', 28)
		#The pyglet.font.Text object to display the FPS
		fps_text = font.Text(ft, y=10)

		while not self.has_exit:
			self.dispatch_events()
			self.clear()

			#Tick the clock
			clock.tick()
			#Gets fps and draw it
			fps_text.text = ("fps: %d") % (clock.get_fps())
			fps_text.draw()

			self.flip()

if __name__ == "__main__":
	# Someone is launching this directly
	space = SpaceGameWindow()
	space.main_loop()

So we are not doing anything that fancy here, first we import three things from the PyGlet library, the window, clock, and font modules. We then create a class called SpaceGameWindow which is a subclass of the pyglet.window.Window class.

Then we have a simple initialization function where for now we simply pass all of the keywords and arguments to the pyglet.window.Window’s __init__() function.

Next we have our main_loop() function which will serve as the main loop for the game. Here we create a pyglet.font.base.Font object and a pyglet.font.Text object that will serve as the font for our “Frames Per Second” text, and the class that will actually write out the “Frames Per Second” text.

After that we have the actual game loop where we continue to loop until the window’s has_exit boolean member variable becomes true.

In the loop we first dispatch all of the event to the event handlers, and then we clear the window to prepare it for drawing. Then we tick the clock, get our FPS text and then draw it out to the screen. Then, since windows in PyGlet are double buffered we flip the display.

Hopefully that is pretty straight forward, if you run the code you should see something similar to the following:

Sprites

Pretty good so far but this doesn’t really help us or do anything, so the next step is to get some stuff draw onto the screen. To do that I’m going to create a simple Sprite class. This class will be loosely based off of the PyGame’s Sprite class, but for the most part will serve as a helper for drawing and the action on the screen.

class Sprite(object):

	def __get_left(self):
		return self.x
	left = property(__get_left)

	def __get_right(self):
		return self.x + self.image.width
	right = property(__get_right)

	def __get_top(self):
		return self.y + self.image.height
	top = property(__get_top)

	def __get_bottom(self):
		return self.y
	bottom = property(__get_bottom)

	def __init__(self, image_file, image_data=None, **kwargs):

		#init standard variables
		self.image_file = image_file
		if (image_data is None):
			self.image = helper.load_image(image_file)
		else:
			self.image = image_data
		self.x = 0
		self.y = 0
		self.dead = False
		#Update the dict if they sent in any keywords
		self.__dict__.update(kwargs)

	def draw(self):
		self.image.blit(self.x, self.y)

	def update(self):
		pass

	def intersect(self, sprite):
		"""Do the two sprites intersect?
		@param sprite - Sprite - The Sprite to test
		"""
		return not ((self.left > sprite.right)
			or (self.right < sprite.left)
			or (self.top < sprite.bottom)
			or (self.bottom > sprite.top))

	def collide(self, sprite_list):
		"""Determing ther are collisions with this
		sprite and the list of sprites
		@param sprite_list - A list of sprites
		@returns list - List of collisions"""

		lst_return = []
		for sprite in sprite_list:
			if (self.intersect(sprite)):
				lst_return.append(sprite)
		return lst_return

	def collide_once(self, sprite_list):
		"""Determine if there is at least one
		collision between this sprite and the list
		@param sprite_list - A list of sprites
		@returns - None - No Collision, or the first
		sprite to collide
		"""
		for sprite in sprite_list:
			if (self.intersect(sprite)):
				return sprite
		return None

So it may look complicated but it’s really not that difficult. First off you will see that I create some positioning properties, left, right, top, and bottom. I do this so that the collision code is easier to read, plus it separates the positioning information from the implementation, in this case the pyglet.image.AbstractImage member. If, in the future we were to add a rectangle class to the Sprite we don’t have to change a the code that interacts with the positioning, just what the position properties interact with.

You will also notice that in the Sprite class can either be initialized using an image file or the actual image data, which is a pyglet.image.AbstractImage. The reason for this is instead of having to load the same image from the hard drive time and time again, and to avoid having the same image duplicated in memory in countless locations, we let the user decide which makes more sense.

Other then that it’s pretty simple stuff, some positioning information, and whether or not the sprite is Alive. If a sprite is dead it will be removed from the window. There is also a draw method where the sprites image is blited to the window, and an update function where (if necessary) the sprite should update itself (position, image, etc).

Next we have a few collision functions that will help us to determine when out sprites collide. Now that we have the sprite class we need to add three more classes based off of the Sprite class. A SpaceShip class, a Bullet class which will be fired by the SpaceShip, and a Monster class.

class SpaceShip(Sprite):

	def __init__(self, text_x, text_y, **kwargs):

		self.kills = 0
		Sprite.__init__(self, "ship.png", **kwargs)

		#Create a font for kill message
		self.font = font.load('Arial', 28)
		#The pyglet.font.Text object to display the FPS
		self.kill_text = font.Text(self.font, y=text_y, x=text_x)

	def draw(self):
		Sprite.draw(self)
		self.kill_text.text = ("Kills: %d") % (self.kills)
		self.kill_text.draw()

	def on_kill(self):
		self.kills += 1

The SpaceShip class doesn’t do that much above and beyond the base class. It has a data member “kills” that keeps track of the number of monsters that it kills, and a pyglet.font.Text member that will display the number of kills on the screen. The position of the “kill text” is also passed into the SpaceShip constructor.

class Bullet(Sprite):

	def __init__(self, parent_ship, image_data, top, **kwargs):
		self.velocity = 5
		self.screen_top = top
		self.parent_ship = parent_ship
		Sprite.__init__(self,"", image_data, **kwargs)

	def update(self):
		self.y += self.velocity
		#Have we gone off the screen?
		if (self.bottom > self.screen_top):
			self.dead = True

	def on_kill(self):
		"""We have hit a monster let the parent know"""
		self.parent_ship.on_kill()

The Bullet class will represent bullets fired by the SpaceShip class, so it adds three new data members the:

1) The velocity – which controls how fast the bullet moves.
2) The screen_top – Which represents the top of the screen is and will be used to destroy the bullet when the bullet moves past the top of the screen.
3) The parent_ship – This is the SpaceShip that fired the bullet. This will be used to let the ship know when it has made a kill.

The final sprite is the Monster sprite:

class Monster(Sprite):

	def __init__(self, image_data, **kwargs):
		self.y_velocity = 5
		self.set_x_velocity()
		self.x_move_count = 0
		self.x_velocity
		Sprite.__init__(self, "", image_data, **kwargs)

	def update(self):
		self.y -= self.y_velocity
		self.x += self.x_velocity#random.randint(-3,3)
		self.x_move_count += 1
		#Have we gone beneath the botton of the screen?
		if (self.y < 0):
			self.dead = True

		if (self.x_move_count >=30):
			self.x_move_count = 0
			self.set_x_velocity()

	def set_x_velocity(self):
		self.x_velocity = random.randint(-3,3)

The Monster sprite will be moving from the top of the screen to the bottom of the screen, which is the opposite of the Bullet and is controlled by the y_velocity data member. But unlike the bullet the Monster sprite will also have some horizontal motion built it, which is controlled by the x_velocity data member, and set in the set_x_velocity() function. What is interesting about the x_velocity is that there is a bit of randomness built into it, it will be a random number from -3 in the left direct to 3 in the right direction. It will also change every thirty updates, giving the Monster a lazy side to side motion making it a bit more difficult for the SpaceShip to shoot it.

The Monster sprite does not have a bottom data member to tell it when it has moved off of the screen. The reason for this is that since the Monster will be moving down from the top of the screen, and we will can tell if it’s off the screen when it’s y, or top, data members are less then zero.

Adding the Sprites to the Game

Now that we have our sprite classes we need to use them in the main SpaceGameWindow class. There are a few ways to do this, but what I ended up doing was creating three new data members: ‘bullets’ and ‘monsters’, both lists of sprites, and ’ship’ which will be the one and only ShapShip sprite.

The Sprites and some other data is initialized in the init_sprites() function:

def init_sprites(self):
	self.bullets = []
	self.monsters = []
	self.ship = SpaceShip(self.width - 150, 10, x=100,y=100)
	self.bullet_image = helper.load_image("bullet.png")
	self.monster_image = helper.load_image("monster.png")

All we do is create the two lists to store our sprites, the SpaceShip sprites, and use our helper to load the images that we will use for the Bullet and Monster sprites.

The next step is to change the draw loop so that we actually draw our sprites. There are a few more changes to be made in the main_loop() function but overall it remains pretty simple:

def main_loop(self):

	#Create a font for our FPS clock
	ft = font.load('Arial', 28)
	#The pyglet.font.Text object to display the FPS
	fps_text = font.Text(ft, y=10)

	#Schedule the Monster creation
	clock.schedule_interval(self.create_monster, 0.3)
	clock.set_fps_limit(30)

	while not self.has_exit:
		self.dispatch_events()
		self.clear()

		self.update()
		self.draw()

		#Tick the clock
		clock.tick()
		#Gets fps and draw it
		fps_text.text = ("fps: %d") % (clock.get_fps())
		fps_text.draw()
		self.flip()

There is quite a bit happening here so I’ll take a little bit of time to explain everything that is new. One of the things that I want to happen is to have monsters created after a certain amount of time has passed. To to this I use the clock.schedule_interval function.

#Schedule the Monster creation
clock.schedule_interval(self.create_monster, 0.3)

What this will do is call the create_monster() function every 0.3 seconds. The create_monster() function is pretty simple, it simply creates a Monster sprite in a random location provided that there is less then the maximum amount of Monsters currently around:


def create_monster(self, interval):
if (len(self.monsters) < self.max_monsters):
self.monsters.append(Monster(self.monster_image
, x=random.randint(0, self.width) , y=self.height))


max_monsters is defined in the __int__() function to be 30. The next new feature is the limiting of the frame rate. For such a simple game I limit it to 30 frames per second using the set_fps_limit function.

Other then that there are only two new calls in the main main loop and that is:

self.update()
self.draw()

update() is basically a function that is used to update everything that is happening on the screen: sprite positions, scores whatever you want. Then the draw() function is basically the function where everything that needs to be drawn onto the screen gets drawn.

def update(self):

	to_remove = []
	for sprite in self.monsters:
		sprite.update()
		#Is it dead?
		if (sprite.dead):
			to_remove.append(sprite)
	#Remove dead sprites
	for sprite in to_remove:
		self.monsters.remove(sprite)

	#Bullet update and collision
	to_remove = []
	for sprite in self.bullets:
		sprite.update()
		if (not sprite.dead):
			monster_hit = sprite.collide_once(self.monsters)
			if (monster_hit is not None):
				sprite.on_kill()
				self.monsters.remove(monster_hit)
				to_remove.append(sprite)
		else:
			to_remove.append(sprite)
	#Remove bullets that hit monsters
	for sprite in to_remove:
		self.bullets.remove(sprite)

	self.ship.update()
	#Is it dead?
	monster_hit = self.ship.collide_once(self.monsters)
	if (monster_hit is not None):
		self.ship.dead = True
		self.has_exit = True

I won’t explain this function too much since in general it’s pretty straight forward. We are basically updating all of the sprites, checking for collisions or them being “dead” and if the sprites need to be removed then we do.

The first step is to update all of the monsters. The second step is to update all of the Bullet sprites and if they are not dead (off the screen) check for a collision between them at the Monster sprites. If the Bullet hits a Monster sprite then it and the monster are both dead and will be removed.

Then we check to see if the SpaceShip sprite has collided with any of the Monster sprites. If it has we signal the end of the game by setting the has_exit window handler.

The draw function is very simple, we simply draw all of the sprites:

def draw(self):

	for sprite in self.bullets:
		sprite.draw()
	for sprite in self.monsters:
		sprite.draw()
	self.ship.draw()

Events

The next step to setup some event handling, which was the whole reason that we made our main class use pyglet.window.Window as the base class way back before we got sidetracked on these sprites and game play.

Fortunately for us adding event handlers is very simple, we simply have to define one of the event functions

Since we want to use mouse motion to move the space ship we need to catch the mouse motion event.

def on_mouse_motion(self, x, y, dx, dy):
	self.ship.x = x
	self.ship.y = y

Pretty simple! We just need to add the function for the even and as long as we call dispatch_events our event will be handed.

We also want the spaceship to fire when we click the left mouse button. So to do that we need to handle the mouse press event.

def on_mouse_press(self, x, y, button, modifiers):

	if (button == 1):
		self.bullets.append(Bullet(self.ship
				, self.bullet_image
				, self.height
				, x=x + (self.ship.image.width / 2) - (self.bullet_image.width / 2)
				, y=y))

Here we simply make sure that it was the left mouse button that was pressed, and it it was we create a bullet in the correct location using the correct image.

PyGlet does something interesting it gives you a mouse drag event, which is sent when a mouse button is down and the mouse is moved. During the “mouse drag” event the “mouse motion” event will not be sent. Sine the used will be clicking a lot we need to keep the Space Ship moving by handling the mouse drag event, if we don’t the ship will seem to pause if we move the mouse and click the left mouse button.

def on_mouse_drag(self, x, y, dx, dy, buttons, modifiers):
	self.ship.x = x
	self.ship.y = y

This is exactly the same as the mouse motion handler, and in truth it could call on_mouse_motion() itself.

Helper

You might have noticed that I use a helper to load this images. This is pretty simple stuff located in a file called “helper.py” in the same directory as PyGletSpace.py:

import os
from pyglet import image

def get_image_dir():
	"""Get the directory used to store the images
	@returns string - the directory
	"""
	directory = os.path.abspath(os.path.dirname(__file__))
	directory = os.path.join(directory, 'data')
	return directory

def load_image(image_file_name):

	full_path = os.path.join(get_image_dir(), image_file_name)
	return image.load(full_path)

Done!

You can download the full source to this tutorial here.

That’s it for this wonderfully short game and lengthy tutorial. What’s I’ve found is that PyGlet is an extremely interesting library that I will continue to keep an eye on. At a certain point I had heard that it was going to be including some Sprite classes and collision classes as well, but it seems as though this may be on the back burner for the initial release.

It will be interesting to see where this goes, what I would like to see would be a simple 2d (since that’s all I’m interested in fooling around with for the most part) engine built on top of PyGlet. A simple way to work with all of the different features that a 2d game needs. Hopefully something like that will come along at some point, heck maybe it’s already out there and I just don’t know about it yet. But if anyone is working on one, or interested in setting something like this up drop me a line.

[1] http://www.pyglet.org/

I just stumbled on this and I thought I’d pass it onto my fellow python programmers, it’s a python 3000 status update from Guido van Rossum.

Personally I’m looking forward to Python 3.0, I don’t know if I’ll like the break in backwards compatibility but a lot of the changes seem great.

Making the print statement a function is a good choice in my opinion.

So instead of:

print "this is printing"

We’ll be using:

print("this is python 3.0")

Also instead of % to format strings, there will be a format() function, which is so much clearer in my opinion.

There are many other changes (say goodbye to old-style classes) so give the link a read and let me know what you think!

Hey everyone, I’ve been getting hit with a bunch of spam comments over the last few days so I’ve made it so that all comments must be moderated before they will appear.

Sorry about this, I don’t like this form of comment posting, but hopefully after a few days I will be able to switch it back to normal.

And sorry about the lack of posts here, yes I am still alive, it’s just that real life has been working me pretty hard these last few weeks.

I’ve been playing around with my PyGTK app and a new PyGame engine that I am working on from the ground up. Something that I can understand and that I can use. I’ll post more information about it when there is more information…right now it does next to nothing!

Hello everyone! This is just a short post to let you all know that I have returned from my holidays eager to start learning Python. My holidays were busy and fun but now that they are done I feel rejuvenated in my quest to learn another programming language.

Also, just to let you know, this site is still under construction and will be worked on and updated in the next few weeks.