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

Package aquarium

Welcome to Aquarium!

Introduction

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.

Philosophy

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 start.py

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/AquariumProperties.py file.

  3. Create an entry point to Aquarium in the way appropriate for your Web server. For instance, see demo/seamstress_exchange/start.py 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
    Aquarium(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.PackagePath
Aquarium allows multiple physical directories to map to a single Python package directory.
aquarium.conf.AquariumProperties
This is the Aquarium configuration file.
aquarium.util.Context
Context instances maintain all the globals for the current Web request. Access to almost everything is through the Context.
aquarium.util.AquariumClass
This is the highest level in the class hierarchy. AquariumClass basically says "I have a Context".
aquarium.util.AquariumTemplate
This is the superclass of all Cheetah templates that subclass AquariumClass.
aquarium.util.Aquarium
This encapsulates the main flow of control for Aquarium.
aquarium.wsadaptor.WebServerAdaptor
This class and its subclasses act as an abstraction layer for all the different types of Web servers.
aquarium.util.InternalLibrary
This is the "standard library" for Aquarium and Aquarium applications. Pay special attention to aquariumFactory, forward, and inverseExtend.
aquarium.screen.ScreenAPI
Screens are the focal point of interaction with the user.
aquarium.layout.LayoutAPI
Layout classes are responsible for laying out the page.
aquarium.layout.CssAndJavaScript
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.
aquarium.navigation.NavigationAPI
Navigation modules encapsulate reusable bits of site navigation.
aquarium.widget.WidgetAPI
Widgets are "other" reusable bits of content. I'm using the word "widget" in its customary meaning for GUI's.
aquarium.widget.FormUtil
This is a "macro" library for generating forms.
aquarium.util.FormDict
All form data is stored in a FormDict.
aquarium.util.FormValid
This is a form validation library.
aquarium.filter.FilterAPI
Once all the content is created, you can run it through a filter.
aquarium.urlscheme.UrlSchemeAPI
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.
aquarium.session.SessionContainer
Each user can be associated with a session; all user sessions are aggregated into a SessionContainer.
aquarium.util.AutoLoader
Classes that mix in the AutoLoader class can dynamically import and instantiate other classes in a syntactically convenient manner.
aquarium.database.DatabaseAssistant
This module documents and enables Aquarium's suggested way of interacting with databases.
aquarium.Style
These are comments and suggestions on style when using Aquarium and Cheetah.
aquarium.History
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.

SourceForge.net Image

SourceForge.net


[1]

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).

Submodules

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

Variable Details

packagePath

Type:
list
Value:
['/home/jj/work/open_source/aquarium/aquarium']                        

Generated by Epydoc 2.1 on Mon Jan 1 16:34:19 2007 http://epydoc.sf.net