Package aquarium :: Package util :: Module Aquarium :: Class Aquarium
[show private | hide private]
[frames | no frames]

Class Aquarium


This class encapsulates the main flow of control for Aquarium.

Almost everything important here can be configured via AquariumProperties. Nonetheless, if you still need more control, feel free to subclass this class. In the entry point of your Web server, you'll need to use your class instead of this class. To replace some of the core Aquarium classes, subclass this, and override the appropriate factory methods of below. The __call__, getInitAndCleanupTaskList, and afterInit methods are also very appropriate for extending or overriding.

The following private variables are used:

_ctx
This is our reference to ctx.
_prevExc, _prevExcInfo
These are used by screenLoop and catchDoubleException.

Method Summary
  __init__(self, wsadaptor)
Accept wsadaptor, and prepare for real work.
  __call__(self)
Handle the request.
  afterInit(self)
Continue after initialization.
  applyFilters(self, buf)
Filter and return the given buf.
  catchDoubleException(self, e)
Call handleDoubleException as needed.
  cleanupContext(self)
Help the garbage collector by emptying self._ctx.
  cleanupDatabase(self)
Close the connection to the database.
  cleanupSession(self)
Call save on the session.
  createContext(self)
  createInternalLibrary(self)
  filterLanguagePreferences(self, languages)
Update the languages list by applying additional logic.
  getInitAndCleanupTaskList(self)
Return all the init and cleanup methods in a list of tuples.
  getLanguagePreferences(self)
Return a list of preferred languages, most preferred first.
  handleDoubleException(self, excInfos)
Handle the case of a double exception.
  initCookies(self)
Get data from cookies, or start a new one.
  initDatabase(self)
Connect to the database.
  initForm(self)
Retrieve the data from the form.
  initGetText(self)
Initialize gettext.
  initSession(self)
Get data from session, or start a new one.
  initSessionCookie(self)
Initialize the session cookie.
  initUrlScheme(self)
Initialize the urlscheme instance.
  screenLoop(self)
Show the desired screen, and loop around to handle exceptions.

Method Details

__init__(self, wsadaptor)
(Constructor)

Accept wsadaptor, and prepare for real work.

This also calls aquarium.util.InternalLibrary.clearModules.

__call__(self)
(Call operator)

Handle the request.

This encapsulates the main flow of control. It is not a violation of encapsulation to read the source of this method.

See tryFinally.

afterInit(self)

Continue after initialization.

This encapsulates the main flow of control. It is not a violation of encapsulation to read the source of this method.

applyFilters(self, buf)

Filter and return the given buf.

Filters are not run from within the big try/except block because you'll probably want filters run for the exception screen as well. Furthermore, filters really shouldn't be expected to raise exceptions on a daily basis.

catchDoubleException(self, e)

Call handleDoubleException as needed.

handleDoubleException raises its own exception, so this method should only return normally on the first exception.

cleanupContext(self)

Help the garbage collector by emptying self._ctx.

This breaks all the circular references. By having everything garbage collected nicely, it insures that all files, such as session files, get closed properly.

cleanupDatabase(self)

Close the connection to the database.

cleanupSession(self)

Call save on the session.

filterLanguagePreferences(self, languages)

Update the languages list by applying additional logic.

If not None, use properties.GETTEXT_ULTIMATE_FALLBACK (which defaults to "en-us") as an ultimate fallback. That means it gets appended to the list of languages if it isn't already there. It also means that if it's in the list of languages, everything after it is deleted.

This deleting behavior is strange but useful. Normally, everything in the code is in "en-us". However, the "en-us" translation catalog is usually empty. If the user requests ["en-us", "zh-cn"] and a translation isn't found for a string in "en-us", you don't want gettext to fallback to "zh-cn". You want it to just use the string itself. Hence, if a string isn't found in the properties.GETTEXT_ULTIMATE_FALLBACK catalog, the string in the source code will be used.

getInitAndCleanupTaskList(self)

Return all the init and cleanup methods in a list of tuples.

This encapsulates the main flow of control. It is not a violation of encapsulation to read the source of this method.

See tryFinally.

getLanguagePreferences(self)

Return a list of preferred languages, most preferred first.

The list may be empty. By default, just use parseAcceptLanguage on the ACCEPT_LANGUAGE header. The list will be passed to filterLanguagePreferences.

handleDoubleException(self, excInfos)

Handle the case of a double exception.

This happens when a normal screen raises an exception, and then later, the exception screen raises an exception.

initCookies(self)

Get data from cookies, or start a new one.

Add the following to self._ctx: cookiesVerified, request.cookie, response.cookie.

initDatabase(self)

Connect to the database.

Add the following to self._ctx: dba, db (via aquarium.database.DatabaseAssistant).

initForm(self)

Retrieve the data from the form.

If an aquarium.util.InternalLibrary.FormValueError is raised, direct the user to the exception screen.

Add the following to self._ctx: form (an instance of aquarium.util.FormDict).

initGetText(self)

Initialize gettext.

Use the class API so that "_" is not globally installed.

Add the following to self._ctx: translation, _, gettext, ngettext. If properties.USE_GETTEXT is False, gettext.NullTranslations. That way, your code will work even if you use _() with gettext turned off.

initSession(self)

Get data from session, or start a new one.

Some session containers subclass aquarium.util.AquariumClass, and some don't. Pass a ctx as necessary.

Add the following to self._ctx: session.

initSessionCookie(self)

Initialize the session cookie.

This is called by initSession.

If HTTPS is currently being used and properties.USE_SECURE_COOKIES is True (the default), the secure attribute will be set. This is good if you're worried about security, but bad if you bounce back and forth between HTTP and HTTPS.

initUrlScheme(self)

Initialize the urlscheme instance.

Add the following to self._ctx: url (an urlscheme).

screenLoop(self)

Show the desired screen, and loop around to handle exceptions.

By using a loop, the same code path can be used for exceptions. In fact:

  • The aquarium.util.InternalLibrary.Forward exception results in looping around to show the desired screen to forward to.
  • ImportError's and AttributeError's while trying to import the screen result in the not_found screen.
  • Any other Exception results in the exception screen.

Be especially wary of infinite loops since we're catching all exceptions and looping around. Use handleDoubleException in these cases, but note that it too will raise an exception, by design.

If a screen runs successfully to completion, if the return value is a generator, just return it. If it is a string, wrap it in a generator and return it.

Add the following to self._ctx: screenList.


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