Package aquarium
[show private | hide private]
[frames | no frames]

Package aquarium

Welcome to Aquarium!


Aquarium is a Web application [1] framework [2], written in Python. It provides an approach to producing a Web application without duplication of effort by reducing the amount of code you need to write. It offers convenient libraries and extensible APIs for items such as session management and Web server integration (including CGI, mod_python, FastCGI, or its own Web server, Glass). It provides tight integration with Cheetah, including autocompilation of Cheetah templates. Last of all, it offers a convenient approach to Web development. As a developer, you just "plug in" modules; Aquarium ties them all together.

Aquarium's features were inspired by a broad range of Web technologies such as PHP's FreeTrade, Java's Struts, Perl's Mason, and Python's Zope. It is Open Source software, available under a BSD-style license. Aquarium is compact--just a few thousand lines of code--and extremely well documented. It's a useful tool for creating any highly-dynamic, custom Web application written in Python.


Aquarium is based around these ideas:

Getting Started

You must download and install Cheetah. Next, download and install Aquarium.

If you have MySQL installed, try the Seamstress Exchange application in the demo directory of an unpacked source distribution. It uses Glass and runs right out of the unpacked source distribution:

$ cd demo/seamstress_exchange
$ python

Otherwise, look for the Web server adaptor class that matches you Web server in the wsadaptor package.

In general getting Aquarium to work with a given Web server involves these steps:

  1. Configure the Web server in whatever way is appropriate for the way you wish to develop Web applications in Python.

  2. Copy and use the Seamstress Exchange application in the demo directory of an unpacked source distribution as a template. At the very least, you'll need a site-packages/conf/ file.

  3. Create an entry point to Aquarium in the way appropriate for your Web server. For instance, see demo/seamstress_exchange/ in an unpacked source distribution. An entry point performs the following tasks:

    • It optionally modifies sys.path and __main__.packagePath.
    • It chooses a Web server adaptor class (e.g. GlassAdaptor).
    • It imports, instantiates, and "executes" a copy of Aquarium via the aquarium.util.Aquarium class. Some Web server adaptors simplify this step. Glass does it automatically.

    For example, here are the critical lines used in an entry point for CGI:

    from aquarium.util.Aquarium import Aquarium
    from aquarium.wsadaptor.CGIAdaptor import CGIAdaptor
  4. Fill out the directories in site-packages with your modules, using Seamstress Exchange as an example.

Learning More

Inspired by literate programming, most of the documentation for Aquarium is available via well-formed Python docstrings:

$ python
>> import aquarium
>> help(aquarium)

The documentation is also available online in HTML format.

Start by reading the Cheetah documentation. Cheetah is a Python-powered template engine and code generator. It is the templating engine used by Aquarium. (Note, you may skip anything related to Webware). Next, check out the Seamstress Exchange demo available in the demo directory of an unpacked source distribution. Finally, you may find the following to be a useful tour of the Aquarium documentation:

Aquarium allows multiple physical directories to map to a single Python package directory.
This is the Aquarium configuration file.
Context instances maintain all the globals for the current Web request. Access to almost everything is through the Context.
This is the highest level in the class hierarchy. AquariumClass basically says "I have a Context".
This is the superclass of all Cheetah templates that subclass AquariumClass.
This encapsulates the main flow of control for Aquarium.
This class and its subclasses act as an abstraction layer for all the different types of Web servers.
This is the "standard library" for Aquarium and Aquarium applications. Pay special attention to aquariumFactory, forward, and inverseExtend.
Screens are the focal point of interaction with the user.
Layout classes are responsible for laying out the page.
This is a higher level layout for HTML screens. It takes care of outputting a generic HTML "template" (including the HTML, HEAD, META, and BODY tags), as well as JavaScript and CSS. Don't let all the autogenerated Cheetah cruft distract you when reading the API.
Navigation modules encapsulate reusable bits of site navigation.
Widgets are "other" reusable bits of content. I'm using the word "widget" in its customary meaning for GUI's.
This is a "macro" library for generating forms.
All form data is stored in a FormDict.
This is a form validation library.
Once all the content is created, you can run it through a filter.
These modules allow you to control the look-and-feel of your URLs. This may be needed for aesthetics, or it may be needed to successfully use a particular Web server.
Each user can be associated with a session; all user sessions are aggregated into a SessionContainer.
Classes that mix in the AutoLoader class can dynamically import and instantiate other classes in a syntactically convenient manner.
This module documents and enables Aquarium's suggested way of interacting with databases.
These are comments and suggestions on style when using Aquarium and Cheetah.
These are some notes on the history of Aquarium and some of its design decisions.

There is additional documentation for various other Aquarium modules, but the above should give you a very solid understanding of Aquarium.

Questions, comments, suggestions, and bug fixes are always welcome on the mailing list. Image


A Web application is an application that users interact with, using their Web browser; it executes business logic on the server the user is interacting with.

The outline of a typical Web application looks something like this:

  1. The user clicks on a link or button.
  2. The application completes any actions that need to be done.
  3. The application prepares data to show to the user.
  4. The application generates HTML (etc.) output.
  5. The user reads and interacts with the output.
  6. Repeat.
[2]A framework is a set of super classes, APIs, and other libraries appropriate for solving a particular domain of problems (in this case, developing a Web application).


Variable Summary
list packagePath = ['/home/jj/work/open_source/aquarium/aquar...

Variable Details



Generated by Epydoc 2.1 on Mon Jan 1 16:34:19 2007