"""Welcome to Aquarium!
Introduction
============
Aquarium is a Web application [#webapp]_ framework [#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.
* `Home page`_
* `Online API documentation`_
* `Glass documentation`_
* `Sourceforge project page`_
* `Download Aquarium`_
* `Mailing list`_
* `Live demo`_
Philosophy
==========
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.
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`_
-------------------------------------------------------------------------------
.. [#webapp] 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.
.. [#framework] 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).
.. _Home page: http://aquarium.sf.net
.. _Online API documentation: http://aquarium.sf.net/api
.. _Glass documentation: http://aquarium.sf.net/glass
.. _Python: http://python.org
.. _FreeTrade: http://share.whichever.com/index.php?SCREEN=freetrade
.. _Struts: http://struts.apache.org
.. _Mason: http://www.masonhq.com
.. _Zope: http://www.zope.org
.. _Cheetah: http://cheetahtemplate.sf.net
.. _mod_python: http://www.modpython.org
.. _Glass: http://aquarium.sf.net/glass
.. _Sourceforge project page: http://sf.net/projects/aquarium
.. _mailing list: http://lists.sf.net/lists/listinfo/aquarium-discussion
.. _live demo: http://jjinux.norcalttora.com:8000
.. _download and install Cheetah:
http://sf.net/project/showfiles.php?group_id=28961
.. _Download Aquarium:
.. _download and install Aquarium:
http://sourceforge.net/project/showfiles.php?group_id=5453
.. _Web server adaptor:
aquarium.wsadaptor.WebServerAdaptor.WebServerAdaptor-class.html
.. _literate programming: http://www-cs-faculty.stanford.edu/~knuth/lp.html
.. _HTML format: http://aquarium.sf.net/api
.. _Cheetah documentation: http://cheetahtemplate.sf.net/docs/users_guide_html
.. |SourceForge.net Image| image::
http://sflogo.sourceforge.net/sflogo.php?group_id=83832&type=1
.. _SourceForge.net: http://sf.net
.. _wsadaptor package: aquarium.wsadaptor-module.html
.. _aquarium.PackagePath: aquarium.PackagePath-module.html
.. _aquarium.conf.AquariumProperties:
aquarium.conf.AquariumProperties-module.html
.. _aquarium.util.Context: aquarium.util.Context.Context-class.html
.. _aquarium.util.AquariumClass:
aquarium.util.AquariumClass.AquariumClass-class.html
.. _aquarium.util.AquariumTemplate:
aquarium.util.AquariumTemplate.AquariumTemplate-class.html
.. _aquarium.util.Aquarium:
aquarium.util.Aquarium.Aquarium-class.html
.. _aquarium.wsadaptor.WebServerAdaptor:
aquarium.wsadaptor.WebServerAdaptor.WebServerAdaptor-class.html
.. _aquarium.screen.ScreenAPI: aquarium.screen.ScreenAPI-module.html
.. _aquarium.util.InternalLibrary:
aquarium.util.InternalLibrary.InternalLibrary-class.html
.. _aquariumFactory:
aquarium.util.InternalLibrary.InternalLibrary-class.html#aquariumFactory
.. _forward:
aquarium.util.InternalLibrary.InternalLibrary-class.html#forward
.. _inverseExtend:
aquarium.util.InternalLibrary.InternalLibrary-class.html#inverseExtend
.. _aquarium.layout.LayoutAPI: aquarium.layout.LayoutAPI-module.html
.. _aquarium.layout.CssAndJavaScript:
aquarium.layout.CssAndJavaScript.CssAndJavaScript-class.html
.. _aquarium.navigation.NavigationAPI:
aquarium.navigation.NavigationAPI-module.html
.. _aquarium.widget.WidgetAPI: aquarium.widget.WidgetAPI-module.html
.. _aquarium.util.FormDict: aquarium.util.FormDict.FormDict-class.html
.. _aquarium.widget.FormUtil: aquarium.widget.FormUtil.FormUtil-class.html
.. _aquarium.util.FormValid: aquarium.util.FormValid-module.html
.. _aquarium.filter.FilterAPI: aquarium.filter.FilterAPI-module.html
.. _aquarium.urlscheme.UrlSchemeAPI: aquarium.urlscheme.UrlSchemeAPI-module.html
.. _aquarium.session.SessionContainer:
aquarium.session.SessionContainer-module.html
.. _aquarium.util.AutoLoader: aquarium.util.AutoLoader.AutoLoader-class.html
.. _aquarium.database.DatabaseAssistant:
aquarium.database.DatabaseAssistant.DatabaseAssistant-class.html
.. _aquarium.Style: aquarium.Style-module.html
.. _aquarium.History: aquarium.History-module.html
"""
__docformat__ = "restructuredtext"
# Created: Tue Mar 30 13:37:55 PST 2004
# Author: Shannon -jj Behrens
# Email: jjinux@users.sourceforge.net
#
# Copyright (c) Shannon -jj Behrens. All rights reserved.
import __main__
import os
import aquarium
if hasattr(__main__, "packagePath"):
packagePath = __main__.packagePath = list(__main__.packagePath)
elif os.environ.has_key("AQUARIUM_PACKAGE_PATH"):
packagePath = __main__.packagePath = \
os.getenv("AQUARIUM_PACKAGE_PATH").split(":")
elif os.path.isdir("site-packages"):
packagePath = __main__.packagePath = ["site-packages"]
else:
packagePath = __main__.packagePath = []
# If a package foo has an Aquarium-style foo/__init__.py that shadows our
# foo/__init__.py, having Aquarium itself in the packagePath is necessary.
packagePath = __main__.packagePath = \
packagePath + [os.path.dirname(aquarium.__file__)]
__path__ = packagePath + __path__
# Now that we have a useable __path__, import AquariumProperties to see if we
# should add the CHEETAH_COMPILE_DIRECTORY to the packagePath.
import aquarium.conf.AquariumProperties as properties
if getattr(properties, "CHEETAH_COMPILE_DIRECTORY", None):
packagePath = __main__.packagePath = \
packagePath + [properties.CHEETAH_COMPILE_DIRECTORY]
__path__.append(properties.CHEETAH_COMPILE_DIRECTORY)
reload(aquarium.conf)
|