RESTfulness in TurboGears

Mark Ramm and I were talking about how to differentiate GET, POST, PUT, and DELETE in TurboGears 2 and we came up with a syntax that's pretty cool. That's not the reason for this post, though. This morning, I noticed that our syntax is completely compatible with TurboGears 1.x -- so here's how you do it.

What we wanted was to expose a RESTful method like this:

class Root(controllers.RootController):

    class index(RestMethod):
        @expose('json')
        def get(self, **kw):
            return dict(method='GET', args=kw)
        @expose('json')
        def post(self, **kw):
            return dict(method='POST', args=kw)
        @expose('json')
        def put(self, **kw):
            return dict(method='PUT', args=kw)
        # NOT exposed, for some reason
        def delete(self, **kw):
            return dict(method='DELETE', args=kw)

The TurboGears 1 implementation relies on the way that CherryPy determines whether a given property is a valid URL controller. It basically looks at the property and checks to make sure that:

• it's callable, and


• it has a property exposed which is true (or
  "truthy")

The "a-ha!" moment came when realizing that:

• Classes are callable in Python (calling a class == instantiating an object)


• Classes can have exposed attributes

So with appropriate trickery behind the scenes, the above syntax should work as-is. So here's the "appropriate trickery behind the scenes":

class RestMeta(type):
    def __new__(meta,name,bases,dct):
        cls = type.__new__(meta, name, bases, dct)
        allowed_methods = cls.allowed_methods = {}
        for name, value in dct.items():
            if callable(value) and getattr(value, 'exposed', False):
                allowed_methods[name] = value
        return cls

The first thing I wanted to do was create a metaclass to use for RestMethod so that I could save the allowed HTTP methods. Nothing too complicated here.

import cherrypy as cp
class ExposedDescriptor(object):
    def __get__(self, obj, cls=None):
        if cls is None: cls = obj
        allowed_methods = cls.allowed_methods
        cp_methodname = cp.request.method
        methodname = cp_methodname.lower()
        if methodname not in allowed_methods:
            raise cp.HTTPError(405, '%s not allowed on %s' % (
                cp_methodname, cp.request.browser_url))
        return True

This next thing is tricky. If you don't understand what a "descriptor" is, I suggest the very nice description here. The basic thing I get here is the ability to intercept a reference to a class attribute the same way the property() builtin intercepts references to object attributes.

The idea here is to use this descriptor as the exposed attribute on the RestMethod class. When CherryPy tries to figure out if the method is exposed, it calls ExposedDescriptor.__get__ and uses the result as the value of exposed. If the HTTP method in question is not exposed, then the code raises a nice HTTP 405 error, which is the correct response to sending, say, a POST to a method expecting only GETs.

The final part of the solution, the actual RestMethod, is actually pretty simple:

class RestMethod(object):
    __metaclass__ = RestMeta

    exposed = ExposedDescriptor()

    def __init__(self, *l, **kw):
        methodname = cp.request.method.lower()
        method = self.allowed_methods[methodname]
        self.result = method(self, *l, **kw)

    def __iter__(self):
        return iter(self.result)

The sequence of things is now this:

• CherryPy traverses along to the root.index class and looks up root.index.exposed


• root.index.exposed is intercepted by the descriptor which checks the CherryPy request method to see if it's valid for this controller, and if it is, returns True


• CherryPy says, "Great! root.index is exposed. So now I'll call root.index(...)." This calls index's constructor, which in turn calls the appropriate method and saves the result in self.result


• CherryPy says "Cool! root.index returned me an iterable object. I'll iterate over it to get the text to send back to the browser." This calls root.index(...).__iter__, which is just delegated to the result that the real controller gave.
  

At then end, we get a fully REST compliant controller with a nice (I think) syntax.

Update 2008-07-21: After some more thinking, I realized that the metaclass isn't necessary. The descriptor is more important, but also not strictly necessary. My original design did everything in the constructor of RestMethod, but this runs after all of TurboGears' validation and identity checking happens, so it's pretty inefficient. If you want the implementation with the descriptor but without the metaclass, you can do this:

import cherrypy as cp
class ExposedDescriptor(object):
    def __get__(self, obj, cls=None):
        if cls is None: cls = obj
        cp_methodname = cp.request.method
        methodname = cp_methodname.lower()
        method = getattr(cls, methodname, None)
        if callable(method) and getattr(method, 'exposed', False):
            return True
        raise cp.HTTPError(405, '%s not allowed on %s' % (
            cp_methodname, cp.request.browser_url))

The benefit to using a metaclass is that the check for the existence, "callability", and exposed-ness of the method happens up front rather than on each request. Also, I don't like the fact that the metaclass pollutes the class namespace with the "allowed_methods" attribute. There's probably a way to clean that up and put the descriptor in a closure, but I haven't had time to look at it. Maybe that will be a future post....