Mass Transit

Over at the Subway project, we've been getting ready for the 0.2 release. This release is a huge stepping stone to Subway 1.0.

Subway, a Python "megaframework", was designed from the ground up to ensure that every single line of code the developer writes is meaningful. It was also designed to keep the total lines of code down without sacrificing readability and ease of maintenance. With so many Web frameworks in the Python world, why did I write Subway? None of the current Web frameworks included everything needed to create a Web application while still remaining flexible (I'm looking at you, Zope). In doing so, I realized that there were still a lot of great tools out there. I decided to reuse as many existing Python components as possible, and as a result, we have a framework that has more mature component parts, a framework that is not the quintessential reinvention of a generic web framework, and a little bit of good PR.

A lot of people have wondered how it compares to other frameworks. Granted, there is a lot of overlap between the various projects, and I'm going to try to explain how Subway is different.

The first (and most controversial) difference that people usually notice is the choice of a templating language, Cheetah. I had several reasons for eliminating contenders such as Kid, ZPT, PTL, DTML, Nevow, PyMeld, my own OneRing and PSP in favor of Cheetah. First of all, Cheetah is already known as one of the most mature templating systems around. Although it is a version 0.9 product, it has many years of development time behind it. Furthermore, such maturity brings mature features, features like object-oriented-document page inheritance to manage larger websites, and excellent documentation. Cheetah is also known for its speed due to its excellent precompilation mechanism. I also wanted a templating language where users did not have to go through a paradigm shift; they could go from hacking code in PHP or standard Python right into Cheetah with a minimal learning curve. Finally, templating languages like Kid, ZPT, Nevow and PyMeld are HTML-only, meaning they cannot generate other document formats like CSS. In my mind, this is unacceptible. Some of these language require your documents to be XML-compliant, which is another no-no. A framework (and templating language) should never get in your way, ever.

Though TurboGears in particular is very, very similar in structure, Subway has a lot of lesser-known features. One of the cooler ones is CherryFlow, a generator-based system that allows you to write a complex Web application as a flow of different pages all in one method. It looks something like this:

@expose
@flow
def example_flow():
    yield view.first_page()
    if request.args["choice"] == "a":
        yield view.choice_a_page()
    else:
        yield view.choice_b_page()
    yield view.last_page()

This sort of functionality is analagous to Cocoon's FlowScript.

Subway also has a form validation framework that makes your life easier. In my incredibly biased opinion, it's the best form validation out there. Every Subway "view" (template object) has an attribute "form", which corresponds to a FormEncode schema that is generated by reading specialized tags and attributes inside the view file. These definitions look something like this:

<form method="post" action="submit_form">
Your name:
<input type="text" name="yourname" form:required="true"
    form:message="You must enter your name" />
<form:error name="yourname" />
<br />
Your e-mail address: <input type="text" name="youremail"
    form:validate="email" form:message="Your must enter a valid e-mail address" />
<form:error name="youremail" />
<br />
<input type="submit" value="Submit" />
</form>

Next, you'll want to hook this up to some Python code to handle the form. That code will look something like this:

@expose
def display_form():
    return view.the_form()

@expose
@form_handler(view.the_form.form)
def submit_form(yourname, youremail):
    if form_submitted:
        if form_errors:
            return view.the_form() # send back the form, Subway will automatically fill in the fields with their submitted values and display all error messages
        else:
          # form is OK
            return view.form_ok()
    # form was not submitted
    return view.the_form()

You can also manually manipulate the form_defaults and form_errors dictionaries to add your own custom validation, or provide a custom-defined FormEncode schema to the form_handler decorator.

A handy little feature of Subway is the docstring views. An example shows it clearly:

@expose
def test_docstring_view():
    """
    This $name is in a docstring
    """
    return test_docstring_view.view(name="view")

Before I sign off for today, let me remind you that a super cool new Ajax framework will be included with the next Subway version, 0.3. Keep an eye out.