Package aquarium
Welcome to Aquarium!
Aquarium is a Web application framework , 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:
- Web applications can be thought of as a combination of a bunch of different
types of modules, such as layouts (what goes where), navigation modules
(e.g. a row of tabs along the top of a page), screens (the main content), and
widgets (other reusable bits of content). Aquarium serves as the framework
for dynamically tying all of these modules together.
- The main request flow of an application involves a controller (written in
Python) that does work and produces data. That data is passed off to a view
(written in Cheetah) that displays that data. See aquarium.screen.ScreenAPI
for more on Aquarium's implementation of the Model/View/Controller paradigm.
Note that Aquarium does not dictate to the developer how the application's
model must work.
- A view's superclass should take care of layout details automatically. In
fact, a view should not need to do anything other than declare who it is
subclassing (who you subclass and how many layers there are in the class
hiearchy should not require you to change the name of your main method). See
aquarium.layout.LayoutAPI for more on this.
- Wherever possible, Aquarium should shelter the developer (or at least help
the developer shelter himself) from things that are likely to change, such
as choice of Web server, choice of RDBMS, or even the look and feel of the
URLs used in the Web application.
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:
Configure the Web server in whatever way is appropriate for the way you wish
to develop Web applications in Python.
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.
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())()
Fill out the directories in site-packages with your modules, using
Seamstress Exchange as an example.
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
| Submodules |
-
conf: Setup the package search path.
-
database: Setup the package search path.
-
filter: Setup the package search path.
-
FilterAPI: Document the API for filter classes.
-
Tidy: Filter the output by running it through HTML Tidy.
-
History: Document the history and influences of Aquarium.
-
layout: Setup the package search path.
-
LayoutAPI: Document the API for layout classes.
-
navigation: Setup the package search path.
-
PackagePath: Document the package search path.
-
parse: Setup the package search path.
-
screen: Setup the package search path.
-
session: Setup the package search path.
-
Style: Comment on style.
-
urlscheme: Setup the package search path.
-
util: Setup the package search path.
-
ActionResults: Use this if you want more than just a string for actionResults.
-
Aquarium: This class encapsulates the main flow of control for Aquarium.
-
AquariumClass: This is the base class for most Aquarium classes.
-
AquariumTemplate: This is the base class for Cheetah templates used with Aquarium.
-
AutoLoader: This mixin supports autoloading.
-
ContainerClass: This is a trivial class that acts like a container.
-
Context: Each request will have a new context.
-
Curry: This class is a curry (think functional programming).
-
FormDict: Translate a cgi.FieldStorage into a (possibly recursive) dict.
-
FormValid: This module contains classes to help validate user input.
-
HasFriends: This mixin supports autoloading of "friend" methods.
-
HTTPResponses: Create constants for the HTTP responses.
-
InternalLibrary: This is the "standard library" for Aquarium's structure.
-
Ports: These are the standard ports for HTTP and HTTPS, etc.
-
ProtectUTF8: Temporarily convert a UTF-8 string to Unicode to prevent breakage.
-
TryFinally: This is a convenient way to deeply nest try/finally statements.
-
widget: Setup the package search path.
-
wsadaptor: Setup the package search path.
-
CGIAdaptor: This subclass of WebServerAdaptor is for CGI environments.
-
FastCGIAdaptor: This subclass of WebServerAdaptor is for FastCGI.
-
GlassAdaptor: This subclass of WebServerAdaptor is for the Glass Web server.
-
ModPythonAdaptor: This subclass of WebServerAdaptor is for mod_python.
-
WebServerAdaptor: This is the base class for wsadaptor classes.
-
WSGIAdaptor: This is a WSGI adaptor for Aquarium.
|
| Variable Summary |
list |
packagePath = ['/home/jj/work/open_source/aquarium/aquar...
|
packagePath
-
- Type:
-
list
- Value:
['/home/jj/work/open_source/aquarium/aquarium']
|
|