__init__.py :  » Web-Frameworks » Aquarium » aquarium-2.3 » aquarium » Python Open Source

Home
Python Open Source
1.3.1.2 Python
2.Ajax
3.Aspect Oriented
4.Blog
5.Build
6.Business Application
7.Chart Report
8.Content Management Systems
9.Cryptographic
10.Database
11.Development
12.Editor
13.Email
14.ERP
15.Game 2D 3D
16.GIS
17.GUI
18.IDE
19.Installer
20.IRC
21.Issue Tracker
22.Language Interface
23.Log
24.Math
25.Media Sound Audio
26.Mobile
27.Network
28.Parser
29.PDF
30.Project Management
31.RSS
32.Search
33.Security
34.Template Engines
35.Test
36.UML
37.USB Serial
38.Web Frameworks
39.Web Server
40.Web Services
41.Web Unit
42.Wiki
43.Windows
44.XML
Python Open Source » Web Frameworks » Aquarium 
Aquarium » aquarium 2.3 » aquarium » __init__.py
"""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)
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.