'''Document the package search path.
Aquarium uses a rarely used feature of Python packages that allows multiple
physical directories to map to a single package directory. In this way,
Aquarium can have its own ``screen`` directory (for instance), and the app can
have its own ``screen`` directory. Both Aquarium and the app form directory
hierarchies that are separate, but overlaid upon each other. A path is used to
search the corresponding directory in each hiearchy for a given module. For
instance, the module reference ``aquarium.navigation.TopNav`` might result in a
search for::
$PYTHON_LIBS/aquarium/navigation/TopNav.py
$APP_LIBS/site-packages/navigation/TopNav.py
$CHEETAH_CACHE/navigation/TopNav.py
The package path must be set once, very early in the life of the application.
Specifically, it must be set before importing, instantiating, and executing
Aquarium or even AquariumProperties (the package path is needed to *find*
AquariumProperties!). The package path is a Python global. Because CGI
executes a new copy of Python for every page hit, in CGI, you must set the
package path at the beginning of every page hit. For other environments, you
normally set the package path at the same time you are initializing other parts
of your application. The package path is determined by one of the following:
* If ``__main__.packagePath`` is set to a tuple of paths, then it is
used. It is common to set ``__main__.packagePath`` in the ``index.py`` of a
CGI::
# In Python.
import __main__
__main__.packagePath = ("/.../site-packages",)
* Otherwise, if the environmental variable ``AQUARIUM_PACKAGE_PATH`` is set to
a colon separated set of paths, then it is used::
# In Bash.
export AQUARIUM_PACKAGE_PATH=/.../site-packages
* Otherwise, if there is a directory named "site-packages" in the current
directory, ``("site-packages",)`` is used.
* Otherwise, an empty tuple is used. Only Aquarium modules will be accessible.
This is helpful when using the Python shell to surf documentation.
Unfortunately, all this magic comes at a modest price. Whenever you create a
new directory that Aquarium doesn't know about (e.g. ``screen/foobar``), you
must create an ``__init__.py`` in that directory that looks like this::
"""Setup the package search path."""
packageType = "screen/foobar" # <- You must update this part.
from __main__ import packagePath
from os import path
__path__ = map(lambda (x): path.join(x, packageType), packagePath) + \\
__path__
Concerning the Python shell, as long as you can reach the aquarium package
(all the various ways to play with ``PYTHONPATH`` are out of scope for this
document), you can use the Python shell to read all of the Aquarium
documentation. To read the documentation for your own application's Aquarium
classes, set the ``AQUARIUM_PACKAGE_PATH`` before starting the shell::
$ env AQUARIUM_PACKAGE_PATH=demo/seamstress_exchange/site-packages \\
python
>>> import aquarium.screen.MessageList
>>> help(aquarium.screen.MessageList)
Unfortunately, this won't work for templates unless you precompile them and put
the directory they are compiled into in your ``AQUARIUM_PACKAGE_PATH``. You'll
need to precompile the base classes too::
$ (cd aquarium;
cheetah-compile --idir . \\
--odir /var/cache/cheetah/seamstress_exchange \\
`find . -name '*.tmpl'`)
$ (cd demo/seamstress_exchange/site-packages
cheetah-compile --idir . \\
--odir /var/cache/cheetah/seamstress_exchange \\
`find . -name '*.tmpl'`)
$ env AQUARIUM_PACKAGE_PATH=demo/seamstress_exchange/site-packages:/var/cache/cheetah/seamstress_exchange python
>>> import aquarium.screen.MessageListView
>>> help(aquarium.screen.MessageListView)
'''
__docformat__ = "restructuredtext"
# Created: Mon Apr 5 14:46:48 PDT 2004
# Author: Shannon -jj Behrens
# Email: jjinux@users.sourceforge.net
#
# Copyright (c) Shannon -jj Behrens. All rights reserved.
|