One of the ways to extend Spyce is with a "Spyce module." This is a historical term, and a little unfortunate because some people have assumed when I talk about "modules" I automatically mean the Spyce variety rather than the vanilla python variety.
A Spyce module is simply a class that extends spyceModule.spyceModule. That's it.
Spyce modules may be used in a .spy page with
[[.import name="modulename"]]
which instructs the compiler to create code that instantiates an instance of the given spyceModule at the beginning of each request for this page. It also automatically invokes the instance's finish method when the request finishes.
What can you do with Spyce modules? A common reason to write a Spyce module -- perhaps the most common -- is is to provide some sort of resource pooling. Here's the spydurus module which does exactly that:
spydurus.py
CONNECTIONS = 3 # max connections to put in the pool
import Queue
from spyceModule import spyceModule
from durus.client_storage import ClientStorage
from durus.connection import Connection
q = Queue.Queue()
for i in range(CONNECTIONS):
q.put(Connection(ClientStorage()))
class spydurus(spyceModule):
def start(self):
self.conn = None
try:
self.conn = q.get(timeout=10)
except Queue.Empty:
raise 'timeout while getting durus connection'
else:
self.conn.abort() # syncs connection
def finish(self, err):
q.put(self.conn)
That's it! (Well, minus some convenience methods dealing with self.conn that are elided for concision here.) Note that finish is always called, even if your code raises an exception, even if you redirect to another page, even if another module's finish method raises.
Most modules can also be usefully used as a python module -- for instance, tododata.py in the Spyce to-do demo uses spydurus.q to get one of the pooled connections in a non-.spy context.
spydurus doesn't need it, but spyceModule also provides a hook into the spyce server in the form of self._api. You can do just about anything from this. I've seen a module that implements cgi_buffer functionality, a module that provides a Struts-style controller, and more. And of course there's all the standard modules.
(Updated links to point to the sf.net site.)
Comments