I've been working on converting an ancient laptop ("vivi", a 166 MHz Pentium) into a digital picture frame. I got the hardware working to my satisfaction a couple weeks ago, so now it's time to work on the software. There are a lot of slideshow programs out there, but I couldn't find any that would allow:

• 1) the ability to display full-screen photos from my Flickr account.
• 2) the ability to be remotely controlled from another machine in our home network.

So I wrote my own slideshow program, using Pygame for graphics and Twisted for networking. Along the way, I picked up a neat design pattern. By using Python's function decorators, my Photo objects can load their metadata (description, tags, URLs) on-demand without much additional code.

I have over 2000 photos in my Flickr library. Information on a single photo can be queried with the flickr.photos.getInfo() function of the Flickr API. This function returns an XML string that gives the description of the photo, a list of tags that have been added to the photo, a list of URLs where the photo is shown, and so on. In the slideshow program, I'm going to have a list of 2000+ Photo objects. I could load the metadata for all 2000 photos when the slideshow starts up, but that's going to cause a heck of a lot of network traffic. The slideshow will be very slow to start up, and Flickr may get angry with me for pounding their servers. Instead, I'd like the metadata for a Photo to be loaded on-demand: only when the slideshow app actually wants the info.

First, here's the naive approach: when a Photo object is created, we'll call the Flickr API to immediately load the metadata. We'll store the XML data structure as self.info, and add some methods that will return the data when it's asked for.

class Photo(object):
    def __init__(self, flickr, id):
        self.info = flickr.photos_getInfo(photo_id=id).photo[0]
 
    def getDescription(self):
        return info.description[0].elementText
 
    def getTags(self):
        result = []
        for tag in self.info.tags[0].tag:
            result.append(tag.elementText)
        return result
 
    def getURLs(self):
        result = []
        for url in self.info.urls[0].tag:
            result.append(url.elementText)
        return result

We can then use the code as follows:

>>> p = Photo(...)
>>> p.getDescription()
"Sword fighting in Yoyogi Park."
>>> p.getTags()
['japan', '2005', 'tokyo', 'yoyogi', 'park', 'september', 'sword', 'fighting', 'kendo']
>>> p.getURLs()
['http://www.flickr.com/photos/colinmcmillen/491114090/']

That works, but if we create 2000 Photo objects when the slideshow starts up, we'll send 2000 API calls to the Flickr website. That's not very nice of us. It'd be better if we set self.description = None in the constructor; then each of our getter methods can call a loadInfo() function only if self.description is still set to None. loadInfo() makes the Flickr API call and sets all the metadata. This solution looks like this:

class OnDemandPhoto(object):
    def __init__(self, flickr, id):
        self.flickr = flickr
        self.id = id
        self.description = None
        self.tags = []
        self.urls = []
 
    def loadInfo(self):
        info = self.flickr.photos_getInfo(photo_id=self.id).photo[0]
        self.description = info.description[0].elementText
        for tag in info.tags[0].tag:
            self.tags.append(tag.elementText)
        for url in info.urls[0].url:
            self.urls.append(url.elementText)
 
    def getDescription(self):
        if self.description is None:
            self.loadInfo()
        return self.description
 
    def getTags(self):
        if self.description is None:
            self.loadInfo()
        return self.tags
 
    def getURLs(self):
        if self.description is None:
            self.loadInfo()
        return self.urls

This code loads the Photo metadata on demand, but the code isn't as clear as it could be. Each of the getter methods has the same check in the first two lines of the function, and it's not immediately obvious what that check is for. Also, I've been glossing over some of the complexities of the Flickr API: some metadata (such as the available picture sizes, geotagging data, etc.) requires calls to additional Flickr API functions. So we will end up with a bunch of on-demand loaders: loadGeoTags(), loadSizes() and a bunch of getters: getGeoTags(), get800x600(), get640x480(), etc. We need to make sure that the right loader is called before each getter computes a value. Putting the appropriate checks to make sure everything is correctly loaded on-demand might start to get hairy.

The general pattern here is that each getter requires an appropriate loader to be called first, but each loader should only ever be called once. So we want to be able to specify two things explicitly:

• 1) a way to say that the data needed for the getFoo() function is loaded by the loadBar() function.
• 2) a way to ensure that each of the loadBar() functions is only called once.

To do this, we'll use function decorators. For now, think of a decorator as some "magic", written on the line before a function definition, that modifies the definition of that function. Specifically, a decorator called @loadedBy will specify that the appropriate loader function gets called before each getter function. A decorator called @callOnce will ensure that each loader function is only executed once per Photo instance. Here's what our example looks like with decorators:

class DecoratedPhoto(object):
    def __init__(self, flickr, id):
        self.flickr = flickr
        self.id = id
        self.description = None
        self.tags = []
        self.urls = []
 
    @callOnce
    def loadInfo(self):
        info = self.flickr.photos_getInfo(photo_id=self.id).photo[0]
        self.description = info.description[0].elementText
        for tag in info.tags[0].tag:
            self.tags.append(tag.elementText)
        for url in info.urls[0].url:
            self.urls.append(url.elementText)
 
    @loadedBy(loadInfo)
    def getDescription(self):
        return self.description
 
    @loadedBy(loadInfo)
    def getTags(self):
        return self.tags
 
    @loadedBy(loadInfo)
    def getURLs(self):
        return self.urls

This code is marginally shorter than the last example, but that's deceiving because I haven't yet shown the implementation of the function decorators. More importantly, the code is well-factored. If I want to add support for another API call (say flickr.photos.getSizes()), I get to re-use my decorators:

    @callOnce
    def loadSizes(self):
        sizes = self.flickr.photos_getSizes(photo_id=self.id).sizes[0].size
        for idx, size in enumerate(sizes):
            width = int(size.attrib['width'])
            height = int(size.attrib['height'])
            url = size.attrib['source']
            self.sizes.append(Size(width, height, url))
 
    @loadedBy(loadSizes)
    def getSizes(self):
        return self.sizes

Now, how are the decorators implemented? A decorator is a function that takes in a function (and maybe some arguments) and returns a new function that should be used instead of the original function. Usually, the decorator takes the original function and transforms it by adding some functionality. This is the Decorator design pattern. Really, Python decorators are just syntactic sugar:

@decorator
def foo():
    doStuff()

is equivalent to:

def foo():
    doStuff()
foo = decorator(foo)

The callOnce() decorator takes in a function fn and ensures that fn called only once per object. The calledBy dict keeps track of which objects have previously called the function. We create a new function result(self) that checks whether self is in calledBy. If it is, we return immediately; otherwise we add self to calledBy, then call fn(self):

def callOnce(fn):
    calledBy = {}
    def result(self):
        if self in calledBy:
            return
        calledBy[self] = True
        fn(self)
    return result

The loadedBy function is a little more complicated because it takes an argument loader. This indicates that loadedBy returns a decorator (which in turn takes in a function and returns a new function.) The important thing here is the function result, which first calls the loader, then calls the decorated function (such as getDescription()):

def loadedBy(loader):
    def decorator(fn):
        def result(self, *args, **kwargs):
            loader(self)
            return fn(self, *args, **kwargs)
        return result
    return decorator

So that's how I've used decorators in my slideshow program. Maybe in a few days I'll explain how I used Twisted to allow the slideshow to be remotely controlled. Also, let me know if you want the slideshow code. I'll probably do an official release in a couple of weeks.

If you liked this post, you might also want to read about creating robot behaviors with Python generators.

Bookmark/search this post with:

delicious | digg | reddit