Compound Thinking

Host TG on IIS

Here’s a quick note on how to use IIS to serve up your TurboGears applications. This is something we need to document better, if we want to increase python/turbogears penetration in the windows market.

It’s not like asp.net is so good that they don’t need TurboGears. And TurboGears multi-threaded+multiprocess model works better on windows than many of the other “dynamic language web-frameworks which depend solely on the multi-process model.

TG Cache

Very useful cache decorator for TG1.

Not sure how I missed this one, but it’s definitely worth a look for anybody trying to scale a TG1 application.

REST and TG

TurboGears has used a tree of controller objects to do URL dispatch since 1.0. Which is nice and easy to understand, and makes getting started very quick. But, it wasn’t always apparent how you should use it to do RESTful dispatch, since the HTTP verbs all ended up going to the same controller method.

You could dispatch within that method, but that never felt totally clean to me. And I’ve been thinking and talking about better ways to do this. The good news is that Rick Copland just “made it happen” after a conversation in atlanta last week.

Using his trick you can write code like this:

class Root(controllers.RootController):

    class person(RestMethod):
        @expose('json')
        def get(self, **kw):
            #...do stuff...
            return dict(method='GET', args=kw)

        @expose('json')
        def post(self, **kw):
             #...do stuff...
            return dict(method='POST', args=kw)

        # NOT exposed
        def delete(self, **kw):
            return dict(method='DELETE', args=kw)

And then HTTP GET and POST verbs will be routed to their respective methods. This makes working with RESTFul api’s easier. And on that front I’m very much looking forward to Dojo 1.2 which has all of kinds of restful json data store goodness.

Hopefully Rick’s recipe can find it’s way into the 1.x core code somewhere so that it’s even easier to do. But for now a couple dozen lines of code gives you everything you need for RESTful goodness.

TG1.x Gets CherryPy 3 compatibility

Looks like the TG 1.x team has been doing good things. CherryPy 3 is support is a very, very good to hear that it’s been integrated into TG1, because this sets the stage for a much longer support cycle for TG1.

CherryPy 3 is a more solid base to work with, and it’s easier to invision supporting it for several years than it was with CherryPy 2.x. And the test-refactoring work that has gone into making this happen is a huge benefit as well, because you will be able to write application level tests that work in tg 1.5 and will still work in 2.0, easing that migration path.

Florent Aide may be on vacation, but things are still moving forward very quickly on the 1.5 front. I’m looking forward to seeing a release with all this great stuff in it.

Sphinx and TG2 docs

We’re hard at work trying to make the TurboGears 2 docs into something best in class. There’s a long way to go, but the toolchain we’re using keeps getting better and better thanks to Sphinx and Bruno José de Moraes Melo and his GSoC work.

Sphinx all by itself provides a great system for turning ReStructured Text (ReST) files into usable documentation. Since the TG docs were in MoinMoin already, and we’d been careful to use ReST, getting started with sphinx was pretty easy. We updated the doc strings in TG2 to take advantage of the sphinx autodoc features to do API level documentiaton.

But the missing piece was pulling example code in from working sample projects. Sphinx had some include helpers, but they weren’t flexible enough for our needs. So, Bruno has created a set of sphinx extensions to help us. The first of these imports working files from projects checked into subversion. This allows us to show progressive enhancement of projects, and it allows us to keep the working example code under the same source control system as the docs.

So now our Wiki20 source doc has sections that look like this:

.. code:: Wiki-20/wiki20/controllers/root.py
   :revision: 4831

Thanks to the sphinx goodness the code this pulls in is going to be color coded for automatically. Bruno has also added the ability to mark of specific snipits of source code so that you can import just the bit you want to show off like this:

.. code:: Wiki-20/wiki20/templates/page.html
    :revision: 4831
    :section: PageName

and where the PageName section is marked off like this:

<!-- ##{PageName} -->
    Page Name Goes Here
<!– ## –>

Bruno is working on a few more extensions to sphinx, that automatically test project code before adding it to the doc, and that automatically zip up the sample project and make it available so that documentation uses can easily download it.

I’m pretty excited about how the docs are shaping up, and I’m hoping that a few more people get involved in writing good docs, because the TG team is very much committed to trying to have the best possible docs. Docs aren’t sexy, but good docs can make or break a the use of a framework for new users getting started, and advanced students who are trying to do complex things.