SnakeStation

A Python-based pumpstation toolkit for internet plumbers

What better thing is there to do with web services than produce more web services?

• Purpose
• Samples
  • Making web pages out of other web pages: TMTOWTDI
  • Filling with data
• Special Features
  • Asynchronous remote requests
  • Tag replacement modes
• Components
  • handlers.py
  • components.py
  • dataclient.py
  • utils.py
• Download and Installation
  • .pyc files
  • shebang lines
• Revision History
  • 1.1 23-Feb-2008
  • 1.0 17-Feb-2008

Purpose

This is a toolkit for quickly producing HTTP-based middleware. Everything is intended to be fetched with HTTP: templates and data services alike.

This means that hosting arrangements can be very flexible, and responsibility for the required components can be distributed: a designer can work up semi-functional mockups and those can be immediately pulled in and utilized to actually produce output. Somebody else can work on the data services.

There is nothing fancy about it. It's self-contained, and if you need an HTML/XML parser or templating language with more features then you can extend this or go to the trouble of picking (and learning) a tool with more features.

Samples

Making web pages out of other web pages: TMTOWTDI

("TMTOWTDI" is the abbreviation for the Perl aphorism "There's more than one way to do it".)

The two examples here are both going to assemble new web pages from the same three templates:

• outer.html - what will be the page wrapper
• inner.html and inner-2.html - two pages which will be used as content within outer.html

The two examples are:

• nested.cgi [source] - the two inner pages are inserted via tag replacement.
• concatenated.cgi [source] - the outer page is disassembled, and the two pieces are concatenated with the inner pages (like bookends).
  

There is a slight difference in the resulting output. In the latter example anything between the %%inner%% and %%inner2%% tags is discarded. (This was done intentionally, to demonstrate that they are different techniques.)

Filling with data

The other nice thing to be able to do is to render data from a data source. We assume you're going to use REST/XML data sources:

• The HTTP request is formatted according to REST.
• The response comes back as unvalidated XML.
  

Here is an example of that:

• potus-04.html - the template
• potus.cgi [source] - the web page, rendered with data
• potus-json.cgi [source] - the handler which emits the  JSON from which the voting results are rendered
  

Special Features

Asynchronous remote requests

There is a limited (and hopefully easily understandable) form of asynchronous fetching. There is a logical point in request processing referred to as "The Gate": fetches which happen before The Gate can be done asynchronously, while fetches which happen after The Gate are always performed synchronously. Processing flow waits at The Gate until all asynchronous template and data fetches have completed.

This mode is turned off by default, but can be enabled on a per-handler basis.

Tag replacement modes

 As demonstrated by nested.cgi, SnakeStation supports insertion of sub-handler content into an outer template. There two insertion modes and three insertion locations which can be combined in different ways:

modes

• Exact - The match string (SPLITTER) must match exactly.
• Regex - The match string is used as a regular expression.
  

locations

• Replace - The inner body replaces the match string.
• Before - The inner body is inserted before the match string.
• After - The inner body is inserted after the match string.
  

Components

You are encouraged to look at the source, of course!

handlers.py

• Generic - The base handler class from which all others are intended to be derived.
• Nester and Inner - Base classes from which nested handlers are intended to be derived.
• TemplatedHTMLFinder - Base class from which classes which render from data sources are intended to be derived.
  

components.py

• Request - More or less a do-nothing subclass of the cgi.FieldStorage class, which encapsulates request information.
• Response - Encapsulates a CGI response.
• ErrorResponse - A default error response.
• InnerResponse - A response class for use by output which is going to be rendered by replacement into a different response.
  

dataclient.py

• XMLResponse - Encapsulates the response from a service request where the data comes in in XML format.
• RESTRequest - Encapsulates a service request which is sent in REST format.
  

utils.py

• Tagged - An extension of the built-in Python str class which helps with taking a bite out of an XML/HTML document.

Download and Installation

1. Download the latest tarball from http://devil.m3047.inwa.net/pub/python/snakestation/latest.tar.
2. Unpack it.

It unpacks as a directory structure which mimics the demonstration site. Alternately you can move the cgi-bin/snakestation/ directory to your Python distribution directory.

.pyc files

You don't need mod_python. However Python scripts do run faster when they can be compiled into .pyc files. This means that immediately after installation, or if you make any updates, your web server needs write access to the directories so that the .pyc files can be regenerated in its context.

shebang lines

Shebang lines aren't even required in all cases. However there are shebang lines in these source files, and they refer to /usr/bin/python. You may need to change them or create a symlink to your actual Python interpreter.

Revision History

More detailed revision information is included in the source files.

1.1 23-Feb-2008

Asynchronous template and data requests. Subhandler injection now supports regular expressions, and before/after insertion as well as replacement.

1.0 17-Feb-2008

Initial release.