spyce
home
license
community
download
examples
resources
wishlist
contrib (@sf)
documentation
intro
lang
runtime
modules
tags
install
exits
sourceforge
statistics
freshmeat

Documentation - Modules
[[ Spyce ]]
Python Server Pages
by Rimon Barr

Prev: 3.7 - Programmatic Interface Up: Table of Contents Next: 4.1 - Request

4. MODULES

The Spyce language, as described above, is simple and small. The Spyce compiler merely embeds the power of Python using special Spyce tags. Most functionality is provided at runtime through Spyce modules and Python modules. A suite of standard Spyce modules is included with the Spyce distribution. The standard Python modules are included in the Python distribution. You, of course, may also write new Spyce modules and Python modules, or use code contributed (sourceforge link) by others to extend the base functionality available in Spyce.

It is important, from the outset, to define what a Spyce module is, and is not. Specifically, it is important to differentiate a Spyce module from a Python module. A Python module is a file with Python code, usually with a common theme, and not necessarily related to Spyce. In contrast, a Spyce module is a file with Python code that is written in a specific way to interact directly with the Spyce runtime engine. A Spyce module may access the internal request and response structures, require per-request startup and tear-down callbacks from the engine, build on the existing standard modules, or alter the behaviour of the runtime engine in some way, whereas a Python module does not.

Both can be imported and used with equal ease at runtime. Spyce modules are imported using the Spyce [[.import]] directive. Python modules are imported using Python import keyword. Remember that modules need to have the same read permissions as regular files that you expect the web server to read.

Once included, a module may be accessed anywhere in the Spyce code as a global variable, just like Python modules. Spyce modules are objects. They provide methods and fields. One uses them as regular Python objects. Modules are start()ed before pre-Spyce processing, and finish()ed post-Spyce processing. They are init()ialized with optional arguments during Spyce processing at the point of the Spyce directive.

Modules may be renamed from their defaults using the as attribute, though this is discouraged in most cases. Doing this may cause unexpected behaviour. The session module, for example, may expect to find or otherwise load a module named cookie in the Spyce environment, if cookies are chosen for session management; the taglib module expects to find the standard stdout module to capture the output of tag body processing; the stdout and filter modules interact very closely with the response module; etc. In other words, you should rename modules only if you have read their implementations and know what you are doing.

The following standard Spyce modules are loaded implictly into the spyce environment, because they are required for Spyce operation: request, response, error, stdout, spylambda and taglib. The latter two are loaded only if Spyce lambdas and active tags are used in the script, respectively. Of the standard Python modules, only the __builtins__ module is imported, along with a number of Spyce exceptions from the spyceException module.

Below, we document each individual standard Spyce module, and then describe how one would write new Spyce modules.


Prev: 3.7 - Programmatic Interface Up: Table of Contents Next: 4.1 - Request

Sub-sections:


© 2002-06 Rimon Barr
email: rimon@acm.org
Spyce Powered SourceForge Logo [[ Spyce ]]
Python Server Pages
version 1.3.13