doc-single.html

	     this would probably come from the database --]]</font>
  <font color="#0000CC">[[ L = [('option %d' %i, str(i)) for i in range(5)] ]]</font>

  &lt;fieldset&gt;
    &lt;legend&gt;Radiolist&lt;/legend&gt;
    <font color="#229922">&lt;f:radiolist class=radio name=radiolist data=&quot;L&quot; default=&quot;3&quot; /&gt;</font>
  &lt;/fieldset&gt;

  &lt;fieldset&gt;
    &lt;legend&gt;Checkboxlist&lt;/legend&gt;
    <font color="#229922">&lt;f:checkboxlist class=radio name=checkboxlist data=&quot;L&quot; default=&quot;=['0', '1']&quot; /&gt;</font>
  &lt;/fieldset&gt;

  &lt;fieldset&gt;
    &lt;legend&gt;Select&lt;/legend&gt;
    <font color="#229922">&lt;f:select name=myselect multiple size=5 data=&quot;L&quot; default=&quot;2&quot; /&gt;</font>
  &lt;/fieldset&gt;

  &lt;fieldset&gt;
    &lt;legend&gt;Date&lt;/legend&gt;
    <font color="#229922">&lt;f:date name=mydate /&gt;</font>
  &lt;/fieldset&gt;

  &lt;h2 style=&quot;clear:both; padding-top: 1em;&quot;&gt;Test it!&lt;/h2&gt;
  &lt;input type=&quot;submit&quot; name=&quot;foo&quot; value=&quot;Submit!&quot;&gt;

<font color="#229922">&lt;/f:form&gt;</font>

</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/formtag.spy">Run this code</a></b>
    </font>
</td></tr></table>

<big><a name="tag_handlers"></a><b>3.9.3. <font color=#ee0000><i>Active Handlers</i></font></b></big><p>


Active Handlers allow you to "attach" python functions to Spyce form submissions.
Instead of old-fashioned inspection of the request environment, Spyce will
pull the parameters required by your function's signature out for you.
Let's have a look at an example. Here, we define a <i>calculate</i>
function and assign it to be the handler for our submit input:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/handlerintro.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#0000CC">[[!
def calculate(self, api, x, y):
    self.result = x * y
]]</font>

<font color="#229922">&lt;spy:parent title=&quot;Active Handler example&quot; /&gt;</font>
<font color="#229922">&lt;f:form&gt;</font>
    <font color="#229922">&lt;f:text name=&quot;x:float&quot; default=&quot;2&quot; label=&quot;first value&quot; /&gt;</font>
    <font color="#229922">&lt;f:text name=&quot;y:float&quot; default=&quot;3&quot; label=&quot;second value&quot; /&gt;</font>

    <font color="#229922">&lt;f:submit handler=&quot;self.calculate&quot; value=&quot;Multiply&quot; /&gt;</font>
<font color="#229922">&lt;/f:form&gt;</font>

&lt;p&gt;
Result: <font color="#CC0000">[[= hasattr(self, 'result') and self.result or '(no result yet)' ]]</font>
&lt;/p&gt;
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/handlerintro.spy">Run this code</a></b>
    </font>
</td></tr></table>
 <p>
<ul>
<li>
Handlers may be inline, as the <i>calculate</i> handler is here, or in a
separate Python module. When using a handler from a Python module, Spyce
will automatically import the module when needed. (Handler parameters are
strings, not Python references.) The <a href=/demos/chat/index.spy>todo demo</a>
demonstrates using handlers this way.
<li>You can give your form inputs a data type; Spyce will perform the
conversion automatically before passing parameters to your handler function.
</ul>
<p>
Active Handlers also make it easy to incorporate user-friendly error messages
into your forms simply by raising a HandlerError:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/handlervalidate.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#0000CC">[[!
def calculate(self, api, x):
    from spyceException import HandlerError
    try:
        x = float(x)
    except ValueError:
        raise HandlerError('Value', 'Please input a number')
    if x &lt; 0:
        raise HandlerError('Value', 'Cannot take the square root of negative numbers!')
    self.result = x ** 0.5
]]</font>

<font color="#229922">&lt;spy:parent title=&quot;Active Handler Validation&quot; /&gt;</font>
<font color="#229922">&lt;f:form&gt;</font>
    <font color="#229922">&lt;f:text name=&quot;x&quot; default=&quot;-1&quot; label=&quot;Value:&quot; /&gt;</font>
    <font color="#229922">&lt;f:submit handler=&quot;self.calculate&quot; value=&quot;Square root&quot; /&gt;</font>
<font color="#229922">&lt;/f:form&gt;</font>

&lt;p&gt;
Result: <font color="#CC0000">[[= hasattr(self, 'result') and self.result or '(no result yet)' ]]</font>
&lt;/p&gt;
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/handlervalidate.spy">Run this code</a></b>
    </font>
</td></tr></table>

<p>
You can show multiple errors at once with a CompoundHandlerError:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/handlervalidate2.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#0000CC">[[!
def errors(self, api):
    from spyceException import HandlerError, CompoundHandlerError
    cve = CompoundHandlerError()
    cve.add(HandlerError('One', 'First error'))
    cve.add(HandlerError('Two', 'Second error'))
    if cve:
        raise cve
]]</font>

<font color="#229922">&lt;spy:parent title=&quot;Active Handler Validation 2&quot; /&gt;</font>
<font color="#229922">&lt;f:form&gt;</font>
    <font color="#229922">&lt;f:submit handler=&quot;self.errors&quot; value=&quot;Show me some errors&quot; /&gt;</font>
<font color="#229922">&lt;/f:form&gt;</font>
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/handlervalidate2.spy">Run this code</a></b>
    </font>
</td></tr></table>

<p>
All Spyce modules are available via the <b>api</b> handler parameter (which
should always be the first parameter (after <b>self</b> in a class). Here
is an example that uses the db module:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/db.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#229922">&lt;spy:parent title=&quot;To-do demo&quot; /&gt;</font>

<font color="#0000CC">[[!
def list_new(self, api, name):
    if api.db.todo_lists.selectfirst_by(name=name):
        raise HandlerError('New list', 'a list with that description already exists')
    api.db.todo_lists.insert(name=name)
    api.db.flush()
]]</font>

(This is an self-contained example using the same database as the
&lt;a href=/demos/to-do/index.spy&gt;to-do demo&lt;/a&gt;.)

&lt;h2&gt;To-do lists&lt;/h2&gt;

<font color="#0000CC">[[ lists = db.todo_lists.select(order_by=db.todo_lists.c.name) ]]</font>
<font color="#229922">&lt;spy:ul data=&quot;[L.name for L in lists]&quot; /&gt;</font>

&lt;h2&gt;New list&lt;/h2&gt;
<font color="#229922">&lt;f:form&gt;</font>
<font color="#229922">&lt;f:submit value=&quot;New list&quot; handler=self.list_new /&gt;</font>:
<font color="#229922">&lt;f:text name=name value=&quot;&quot; /&gt;</font>
<font color="#229922">&lt;/f:form&gt;</font>
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/db.spy">Run this code</a></b>
    </font>
</td></tr></table>

<p>
Handlers in <a href="#tag_new2">Active Tags</a> allow you to
create reusable components, as in the the <a href=/demos/chat/index.spy>chat demo</a>.
<p>
(Since Spyce captures stdout, you can use <b>print</b> to debug handlers.)
<big><a name="tag_new2"></a><b>3.9.4. <font color=#ee0000><i>Writing Tag Libraries</i></font></b></big><p>

Creating your own active tags is quite easy and this section explains how. You
may want to create your own active tags for a number of reasons. More advanced
uses of tags include database querying, separation of business logic, or
component rendering. On the other hand, you might consider creating simpler
task-specific tag libraries. For example, if you do not wish to rely on
style-sheets you could easily define your own custom tags to perform the
formatting in a consistent manner at the server. Another convenient use for
tags is to automatically fill forms with session data. These are only a few of
the uses for tags. As you will see, writing a Spyce active tag is far
simpler than writing a JSP tag.
<p>
(The <a href=/demos/chat/index.spy>chatbox demo</a> gives an example of an active tag.)
<p>
Tag libraries must be placed in a separate file from request-handling Spyce pages.
The following
<a href="#lang_directive">directives</a>
apply specifically to tag library definition:
<ul>
<li><font face=courier>
[[.<b>tagcollection</b>&nbsp;]] </font>:
<br>Indicates that the current file will be an Active Tag library. Must
be at the start of the file.
<li><font face=courier>
[[.<b>begin</b>&nbsp;name=<i>string</i>&nbsp;[buffers=<i>True|<b>False</b></i>]&nbsp;[singleton=<i>True|<b>False</b></i>]&nbsp;[kwattrs=<i>string</i>]&nbsp;]] </font>:
<br>
Begin defining a tag named <i>name</i>. Optional attributes:
<ul>
<li>buffers: if true, Spyce will evaluate the code between the begin and end tags
and pass it to the tag as the variable _content. For instance, the following
simplistic tag makes its contents bold:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/tagbold.spi</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#CC00CC">[[.begin name=bold buffers=True]]</font>

&lt;b&gt;<font color="#CC0000">[[=_contents]]</font>&lt;/b&gt;

<font color="#CC00CC">[[.end]]</font></b></font></pre>
  </font>
</td></tr></table>
 <li>singleton: if true, Spyce will not allow paired use of the tag (&lt;tag&gt;&lt;/tag&gt;)
and only allow singleton use (&lt;tag /&gt;). If false, the reverse is true.
<li>kwattrs: the name of the dict in which to place attributes not specified with [[.attr]]
directives. If not given, Spyce will raise an error if unexpected attributes are seen.
</ul>
<li><font face=courier>
[[.<b>attr</b>&nbsp;name=<i>string</i>&nbsp;[default=<i>string</i>]&nbsp;]] </font>:
<br>Specify that the current tag being defined expects an attribute named <i>name</i>.
If a default string is given, the attribute is optional. (Dynamic attributes
may be accepted with the kwattrs option in the begin directive.) (If the default
string is prefixed with '=', it will be evaluated as python code at runtime.)
<li><font face=courier>
[[.<b>export</b>&nbsp;var=<i>string</i>&nbsp;[as=<i>string</i>]&nbsp;]] </font>:
<br>Specifies that the variable from the tag context named <i>var</i> will be
exported back to the calling page. The optional <i>as</i> attribute may be used
to give the variable a different name in the calling context.
<li><font face=courier>
[[.<b>end</b>&nbsp;]] </font>:
<br>Ends definition of the current tag.
</ul>
Active tags may specify <a href="#tag_handlers">handlers</a>
as in normal Spyce code; this may be done inline
with <a href="#lang_chunkc">class chunks</a>, or as a reference
to a separate .py module. This allows building reusable components easily!
Again, the <a href=/demos/chat/index.spy>chatbox demo</a> demonstrates this.
<p>
(Be careful if you take the class chunk approach with handlers, since all class chunks that get used
in a given page are pulled into the same namespace. By convention, tag handlers
defined in reusable tags are prefixed with the tag name, e.g., chatbox_addline.)
<p>
Active tags should <i>not</i> contain f:form active tags; this needs to be done
by the .spy page for the Spyce compiler to link up Active Handlers correctly.
<p>
One limitation of using the Active Tag directives described here is that tags
within a single collection may not call each other. Usually, you can work
around this by defining common code inside a .py module and importing that.
If this is not an option, you can create Active Tags manually. This is
described in the next section.
<big><a name="tag_new"></a><b>3.9.5. <font color=#ee0000><i>Writing Tag Libraries the hard way</i></font></b></big><p>


You can still write tag libraries manually if the tag declaration language doesn't
give you the tools you need. (About the only functionality it doesn't currently
expose is the looping ability used in spy:for.) You may wish to approximate
what you want with a <a href="#tag_new2">new-style tag library</a>
and examine the compiler's output (spyceCmd.py -c).
<p>
We begin with a basic example: <p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/myTaglib.py</b></font>
</td></tr><tr><td>
  <font face=courier>
    
<style>    
.STRING {
  color: #a0522d;
}
.COMMENT {
  color: #ff7448;
  font-family: serif;
}
.KEYWORD {
  color: #9e79af;
}
.FUNCTION {
  color: #0074ef;
}
</style>
<pre>
<span class="KEYWORD">from</span> <span class="NAME">spyceTag</span> <span class="KEYWORD">import</span> <span class="NAME">spyceTagLibrary</span><span class="OP">,</span> <span class="NAME">spyceTagPlus</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="KEYWORD">class</span> <span class="FUNCTION">tag_foo</span><span class="OP">(</span><span class="NAME">spyceTagPlus</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">  </span><span class="NAME">name</span> <span class="OP">=</span> <span class="STRING">'foo'</span><span class="NEWLINE">
</span>  <span class="NAME">mustend</span> <span class="OP">=</span> <span class="NUMBER">1</span><span class="NEWLINE">
</span>  <span class="KEYWORD">def</span> <span class="FUNCTION">syntax</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">    </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">syntaxPairOnly</span><span class="OP">(</span><span class="OP">)</span><span class="NEWLINE">
</span>    <span class="NAME">self</span><span class="OP">.</span><span class="NAME">syntaxNonEmpty</span><span class="OP">(</span><span class="STRING">'val'</span><span class="OP">)</span><span class="NEWLINE">
</span>  <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">begin</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="NAME">val</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">    </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">getOut</span><span class="OP">(</span><span class="OP">)</span><span class="OP">.</span><span class="NAME">write</span><span class="OP">(</span><span class="STRING">'&lt;font size="%s"&gt;&lt;b&gt;'</span> <span class="OP">%</span> <span class="NAME">str</span><span class="OP">(</span><span class="NAME">val</span><span class="OP">)</span><span class="OP">)</span><span class="NEWLINE">
</span>  <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">end</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">    </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">getOut</span><span class="OP">(</span><span class="OP">)</span><span class="OP">.</span><span class="NAME">write</span><span class="OP">(</span><span class="STRING">'&lt;/b&gt;&lt;/font&gt;&lt;br&gt;'</span><span class="OP">)</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="DEDENT"></span><span class="DEDENT"></span><span class="KEYWORD">class</span> <span class="FUNCTION">myTaglib</span><span class="OP">(</span><span class="NAME">spyceTagLibrary</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">  </span><span class="NAME">tags</span> <span class="OP">=</span> <span class="OP">[</span><span class="NL">
</span>    <span class="NAME">tag_foo</span><span class="OP">,</span> <span class="NL">
</span>  <span class="OP">]</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="DEDENT"></span><span class="ENDMARKER"></span>
</pre>
    
  </font>
</td></tr></table>
 <p>
Saving this code in <font face=courier>myTaglib.py</font>, in the same
directory as your script or anywhere else in the search path, one could then
use the <b>foo</b> active tag (defined above), as follows: <p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/tag.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#CC00CC">[[.taglib name=myTaglib as=me]]</font>
&lt;html&gt;&lt;body&gt;
<font color="#0000CC">[[ for x in range(2, 6):{ ]]</font>
  <font color="#229922">&lt;me:foo val=&quot;=x&quot;&gt;</font>size <font color="#CC0000">[[= x ]]</font><font color="#229922">&lt;/me:foo&gt;</font>
<font color="#0000CC">[[ } ]]</font>
&lt;/body&gt;&lt;/html&gt;
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/tag.spy">Run this code</a></b>
    </font>
</td></tr></table>
 <p>
An active tag library can be any Python class that derives from
<b>spyceTag.spyceTagLibrary</b>. The interesting aspects of this class
definition to implementors are: <p>
<ul>
<li><b>tags</b>: <br> This field is usually all that requires redefinition.
It should be a list of the <i>classes</i> (as opposed to instances) of the
active tags. </li> <p>
<li><b>start</b>(): <br> This methd is invoked by the engine upon loading
the library. The inherited method is a noop. </li> <p>
<li><b>finish</b>(): <br> This method is invoked by the engine upon
unloading the library after a request. The inherited method is a noop. </li>
<p>
</ul>
Each active tag can be any Python class that derives from
<b>spyceTag.spyceTag</b>. The interesting aspects of the class definition for
tag implementors are: <p>
<ul>
<li><b>name</b>: <br> This field MUST be overidden to indicate the name of
the tag that this class defines. </li> <p>
<li><b>buffer</b>: <br> This flag indicates whether the processing of the
body of the tag should be performed with the current output stream
(unbuffered) or with a new, buffered output stream. Buffering is useful for
tags that may want to transform, or otherwise use, the output of processing
their own bodies, before it is sent to the client. The inherited default is
false. </li> <p>
<li><b>conditional</b>: <br> This flag indicates whether this tag may
conditionally control the execution of its body. If true, then the begin()
method of the tag must return true to process the tag body, or false to skip
it. If the flag is set to false, then return value of the begin() method is
ignored, and the body executed (unless an exception is triggered). Some
tags, such as the <font face=courier>core:if</font> tag, require this
functionality, and will set the flag true. Many other kinds of tags do not,
thus saving a level of indentation (which is unfortunately limited in Python
-- hence the need for this switch). The inherited default is false. </li>
<p>
<li><b>loops</b>: <br> This flag indicates whether this tag may want to loop
over the execution of its body. If true, then the body() method of the tag
must return true to repeat the body processing, or false to move on to the
end() of the tag. If the flag is set to false, then the return value of the
body() method is ignored, and the body is not looped. Some tags, such as the
<font face="courier">core:for</font> tag, require this functionality, and
will set the flag true. Many other kinds of tags do not, thus saving a level
of indentation. The inherited default is false. </li> <p>
<li><b>catches</b>: <br> This flag indicates whether this tag may want to
catch any exceptions that occur during the execution of its body. If true,
then the catch() method of the tag will be invoked on exception. If the flag
is false, the exception will continue to propagate beyond this point. Some
tags, such as the <font face="courier">core:catch</font>, require this
functionality, and will set the flag true. Many other kinds of tags do not,
thus saving a level of indentation. The inherited default is false. </li>
<p>
<li><b>mustend</b>: <br> This flag indicates whether this tag wants the
end() method to get called, if the begin() completes successfully, <i>no
matter what</i>. In other words, the call to end() is placed in the finally
clause of
the try-finally block which begins just after the begin(). This is useful for
tag cleanup. However, many tags do not perform anything in the
end() of their tag, or perhaps perform operations that are not important in
the case of an exception. Such tags do not require this functionaliy, thus
saving a level of indentation. The inherited default is false. </li> <p>
<li><b>syntax</b>(): <br> This method is invoked at compile time to perform
any additional tag-specific syntax checks. The inherited method returns
None, which means that there are no syntax errors. If a syntax error is
detected, this function should return a string with a helpful message about
the problem. Alternatively, one could raise an
<b>spyceTagSyntaxException</b>. </li> <p>
<li><b>begin</b>( ... ): <br> This method is invoked when the corresponding
start tag is encountered in the document. All the attributes of the tag are
passed in by name. This method may return a boolean flag. If
<b>conditional</b> is set to true (see above), then this flag indicates
whether the body of the tag should be processed (true), or skipped (false).
The inherited method performs no operation, except to return true. </li> <p>
<li><b>body</b>( contents ): <br> This method is invoked when the body of
the tag has <i>completed</i> processing. It will be called also for a
singleton, which we assume simply has an empty body. However, it will not be
called if the begin() method has chosen to skip body processing entirely. If
the tag sets <b>buffer</b> to true for capturing the body processing output
(see above), then the string output of the body processing has been captured
and stored in <b>contents</b>. It is the responsibility of this method to
emit something, if necessary. If the tag does not buffer then
<b>contents</b> will be None, and any output has already been written to the
enclosing scope. If the <b>loops</b> flag is set to true, then this method
is expected to return a boolean flag. If the flag is true, then the body
will be processed again, followed by another invocation of this method. And
again, and again, until false is received. The inherited tag method performs
nothing and returns false. </li> <p>
<li><b>end</b>(): <br> This method is invoked when the corresponding end tag
is encountered. For a singleton tag, we assume that the end tag immediately
follows the begin, and still invoke this method. If the <b>mustend</b> flag
has been set to true, then the runtime engine semantics ensure that if the
begin method terminates successfully, this method <i>will</i> get called,
even in the case of an exception during body processing. The inherited
method is a noop. </li> <p>
<li><b>catch</b>( ex ): <br> If the <b>catches</b> flag has been set to
true, then if any exception occurs in the begin(), body() or end() methods
or from within the body processing, this method will be invoked. The
parameter <b>ex</b> holds the value that was thrown. The inherited method
simply re-raises the exception. </li> <p>
<li><b>getPrefix</b>(): <br> Return the prefix under which this tag library
was installed. </li> <p>
<li><b>getAttributes</b>(): <br> Return a dictionary of tag attributes.
</li> <p>
<li><b>getPaired</b>(): <br> Return true if this is a paired (open and
close) tag, or false if it is a singleton. </li> <p>
<li><b>getParent</b>( [name] ): <br> Return the object of the direct parent
tag, or None if this is the root active tag. Plain (inactive) tags do not
have objects associated with them in this hierarchy. If the optional
<b>name</b> parameter is provided, then we search up the tree for an active
tag of the same library and with the given name. If such a tag can not be
found, then return None. </li> <p>
<li><b>getOut</b>(): <br> Return the (possibly buffered) output stream that
this tag should write to. </li> <p>
<li><b>getBuffered</b>(): <br> Returns true if the tag output stream is a
local buffer, or false if the output is connected to the enlosing scope.
</li> <p>
</ul>
Note that Spyce goes to a lot of effort to avoid unnecessary indentation in
the code it generates for Active Tags.
A limitation of the Python runtime is that the level of indentation
within any method is limited by a
compile-time constant. You can change it, of course, but in most
Python distributions as of this writing (Feb 2005), this is currently set to 100.
See for instance
<a href="http://mail.python.org/pipermail/python-bugs-list/2003-June/018148.html">this thread</a>
from python-bugs.
<p>
For convenience, tag implementors may wish to derive their implementations
from <b>spyceTagPlus</b>, which provides some useful additional methods:
<ul>
<li><b>getModule</b>( name ): <br> Return a reference to a module
from the page context. The module is loaded, if necessary. </li> <p>
<li><b><s>syntaxExist</b>( [must]* )</s>: <br> Removed in 2.0;
Spyce now checks the signature of the begin method; arguments
with no default are enforced as required automatically. <p>
<li><b>syntaxNonEmpty</b>( [names]* ): <br> Ensure that if the attributes
listed in <b>names</b> exist, then each of them does not contain an empty
string value. Otherwise, a spyceTagSyntaxException is thrown. Note that the
actual existence of a tag is checked by syntaxExists(), and that this method
only checks that a tag is non-empty. Specifically, there is no exception
raised from this method, if the attribute does not exist. </li> <p>
<li><b>syntaxValidSet</b>( name, validSet ): <br> Ensure that the value of
the attribute <b>name</b>, if it exists, is one of the values in the set
<b>validSet</b>. Otherwise, a spyceTagSyntaxException is raised. </li> <p>
<li><b>syntaxPairOnly</b>(): <br> Ensure that this tag is a paired tag.
Otherwise, a spyceTagSyntaxException is thrown. </li> <p>
<li><b>syntaxSingleOnly</b>(): <br> Ensure that this tag is a singleton tag.
Otherwise, a spyceTagSyntaxException is thrown. </li> <p>
</ul>
Despite the length of this description, most tags are trivial to write, as
shown in the initial example. The easiest way to start is by having at a look
at various implemented tag libraries, such as <font
face=courier>tags/core.py</font>. The more curious reader is welcome to look
at the tag library internals in <font face=courier>spyceTag.py</font> and
<font face=courier>modules/taglib.py</font>. The tag semantics are ensured by
the Spyce compiler (see <font face=courier>spyceCompile.py</font>), though it
is likely easier simply to look at the generated Python code using the <font
face=courier>"spyce&nbsp;-c"</font> command-line facility. <p>

<big><a name="conf"></a><b>3.10. <font color=#ee0000>Installation</font></b></big><p>


Spyce can be installed and used in many configurations. Hopefully, one of the
ones below will suit your needs. If not, feel free to email the lists asking
for assistance in using a different setup. If you have successfully set up
Spyce by some other method, please also email us the details.
Finally, if you had troubles following these instructions,
please send suggestions on how to improve them. <p>
<big><a name="conf_overview"></a><b>3.10.1. <font color=#ee0000><i>Overview</i></font></b></big><p>


Spyce (the core engine and all the standard modules) currently requires
<b>Python version 2.3 or greater</b>. Spyce uses no version-specific Apache features. <p>
Spyce supports operation through
its own webserver, FastCGI, mod_python, Apache proxy, CGI, and the command-line.
Some of these require configuration-specific tweaks. These are kept to an
absolute minimum, however; where possible, the configuration of the
Spyce engine is performed through the
<a href=#runtime_common>Spyce configuration module</a>.
The supported adapters are:
<ul>
<li> <b>Web server:</b> The preferred alternative is to serve Spyce files via
its built-in webserver. For production use, it is recommended to do this
as a proxy behind another server such as Apache that handles static content,
url rewriting, ssl, etc.
This is the best option if it is available to you, since you only
have a single process (with concurrency provided by multithreading) which
makes resource pooling (data, database handles, etc.) an easy way to help
your site scale. It also avoids the waste of loading your code into
multiple Python interpreters.
</li> <p>
<li> <b>FastCGI:</b>
This is a CGI-like interface that
is relatively fast, because it does not incur the large process startup
overhead on each request. </li> <p>
<li> <b>mod_python:</b> This is another relatively performant
way to serve up Spyce.
If this is that is your chosen Apache integration route,
make sure you can first get mod_python running on your system, before
adding Spyce to the mix.
</li> <p>
<li> <b>CGI:</b> Failing these alternatives, you can always process requests
via regular CGI, but this alternative is the slowest option and is intended
primarily for those who do not have much control over their web environments.
</li> <p>
<li> <b>Command line:</b> Spyce is useful as a command-line tool
for pre-processing Spyce pages and creating static HTML files.
This documentation, for instance, is produced this way.
</li> <p>
<li><b>Others</b>: Spyce abstracts its operating environment using a thin
abstraction layer. Spyce users have written small Spyce adapters for the
Xitami webserver and also to integrate with the Coil framework. Writing your
own adapter, should the need arise, is therefore a realistic possibility.
</li><p>
</ul>
The following sections assume that you have already <a href=get.html>downloaded</a> and uncompressed Spyce.
<big><a name="conf_proxy"></a><b>3.10.2. <font color=#ee0000><i>Web Server</i></font></b></big><p>


The preferred method of running Spyce it to run it as a web-server.
<p>
The Spyce web server configuration is defined in the "webserver options" section
of the <a href="#runtime_common">Spyce configuration module</a>.
<ul>
<li>Start the Spyce web server. The command-line syntax for starting the
server is: <br> <b><font face=courier>spyceCmd.py -l</font></b>
<br>
Spyce will now be running on port 8000. You can change the port in your
<a href="#runtime_common">spyceconf module</a>.
</li>
<li>If you are going to proxy Spyce behind Apache (this is done automatically if you installed via RPM):
<ol>
<li>Copy the proxy section ("Spyce via proxy") from spyceApache.conf into httpd.conf.
<li>Make sure mod_proxy is installed and enabled. Check httpd.conf for a mod_proxy
section; look for instructions like "Uncomment the following lines to enable the proxy server."
<li>Restart Apache</li>
</ol>
</li>
</ul>
<big><a name="conf_source"></a><b>3.10.3. <font color=#ee0000><i>CGI/FastCGI installation</i></font></b></big><p>


<ul>
<li>Ensure that you have Apache and FastCGI installed and functioning.</li>
<li>Create a symlink to the command-line executable: <br> <font
face=courier><b>ln&nbsp;-sf&nbsp;/usr/share/spyce/run_spyceCmd.py&nbsp;/usr/bin/spyce</b></font>
<br> or wherever you have chosen to install it. </li>
<li>Copy the "Spyce via cgi or fcgi" lines from spyceApache.conf to your
<font face=courier><b>/etc/httpd/conf/httpd.conf</b></font>
file, and replace the <font color=red><b>XXX</b></font> with the appropriate
path to your spyce installation.
<li>Restart Apache
</ul>
<b>Alternative CGI configuration:</b>
The alternative CGI configuration directs the webserver to execute the .spy
file itself, not the Spyce engine. This is appropriate if you do not control
Apache on the server you are installing to, e.g., low-end hosting
plans. Each .spy file should have execute
permissions for the web server, and the first line should be:
<p>

<font face=courier>
<pre>
  #!/usr/bin/python /home/username/spyce/run_spyceCGI.py
</pre>
</font>

(Adjust to the correct Spyce installation path as necessary.)
Then add the following line to the <font face=courier>httpd.conf</font>, or to
the <font face=courier>.htaccess</font> file in the same directory.

<font face=courier>
<pre>
  AddHandler cgi-script spy
</pre>
</font>

Finally, ensure that the directory itself has the <b>ExecCGI</b> option enabled,
and set <font face=courier>cgi_allow_only_redirect</font> to
<font face=courier>False</font> in your Spyce configuration module.
For more details, please refer to the Apache documentation, specifically
<a href="http://httpd.apache.org/docs/mod/core.html#options">ExecCGI option</a>,
<a href="http://httpd.apache.org/docs/mod/core.html#directory">Directory</a>,
<a href="http://httpd.apache.org/docs/mod/core.html#location">Location</a>,
<a href="http://httpd.apache.org/docs/mod/core.html#allowoverride">AllowOverride</a> and
<a href="http://httpd.apache.org/docs/howto/cgi.html">Apache CGI documentation</a>,
for more information on how to get a standard CGI setup working. <p>
<big><a name="conf_modpython"></a><b>3.10.4. <font color=#ee0000><i>Mod_Python</i></font></b></big><p>


mod_python is primarily recommended if you cannot get
FastCGI to work. (Some users have reported problems with FastCGI on Windows.)
<p>
Before you try to install Spyce, first get mod_python to work!
You may have to compile from sources, and possibly do the same for Python. (See
the documentation at: <a href="http://www.modpython.org">mod_python</a>.)
<p>
To use Spyce via mod_python:
<ul>
<li>Copy the "Spyce via mod_python" lines from spyceApache.conf to your
<font face=courier><b>/etc/httpd/conf/httpd.conf</b></font>
file, and replace the <font color=red><b>XXX</b></font> with the appropriate
path to your spyce installation.
<li>Restart Apache
</ul>
<big><a name="conf_windows"></a><b>3.10.5. <font color=#ee0000><i>Notes for Windows</i></font></b></big><p>


Besides your preferred installation option above, remember to
add the following line to Apache's httpd.conf: <p>

<font face=courier>
<b><pre>
  ScriptInterpreterSource registry
</pre></b>
</font>
<p>
This assumes that Python has registered itself with the Windows registry to
run .py files. Otherwise, you can also omit this line, but make sure that the
first line of the <font face=courier>run_spyceCGI.py</font> file points to a
valid Python executable, as in:

<font face=courier>
<b><pre>
  #! c:/python24/python.exe
</pre></b>
</font>
<p>
If you are running using IIS on Windows, you can take a look at
<a href="http://starship.python.net/crew/aaron_watters/pws.html">how to
configure IIS or PWS for Python/CGI scripts</a>. <p>
The basics for getting IIS to work with Spyce are:
<ul>
<li> Start the IIS administration console. You get to it from the <b>Control
Panel</b>. Click on <b>Administrative Tools</b>, and then <b>Internet
Services Manager</b>. </li>
<li> Drill down to your <b>Default Web Site</b>. Right click and select
<b>Properties</b>. </li>
<li> Select the <b>Home Directory</b> tab, and click on the
<b>Configuration...</b> button near the bottom right. </li>
<li> Add an application mapping. On the <b>executable</b> line you should
type the equivalent of: <br> <b><font
face=courier>"c:\program&nbsp;files\python22\python.exe"&nbsp;"c:\program&nbsp;files\spyce\spyceCGI.py"</font></b>.
<br> Set the <b>extension</b> to <b><font face=courier>.spy</font></b>, or
whatever you like. <br> Limit the <b>Verbs</b> to <b><font
face="courier">GET,POST</font></b>. <br> Select the <b>Script engine</b> and
<b>Check that file exists</b> check-boxes. </li>
<li>Click <b>OK</b> twice. Make sure to propagate these properties to all
sub-nodes. That is, click <b>Select All</b> and then <b>OK</b> once more.
</li>
<li> You should now be able to browse .spy files within your website. Note,
that this is a very slow mechanism, since it utilizes CGI and restarts the
Spyce engine on each request. </li>
<li> Using the Spyce proxy web server or installing FastCGI are much
advised for the vast majority of environments. </li>
</ul>
<big><a name="conf_rpm"></a><b>3.10.6. <font color=#ee0000><i>Notes on RPM installation</i></font></b></big><p>


<ul>
<li>The RPM installation installs Spyce to /usr/share/spyce and
creates a /usr/bin/spyce as a symlink to spyceCmd.py. It also
configures Apache to forward .spy requests to the Spyce server on port 8000.
You're still responsible for starting the spyce server as described in the
<a href="#conf_proxy">Web Server</a> configuration section.
<li>If you upgrading Spyce, it is recommended to uninstall the previous
version using <b>rpm -e spyce</b>, and then install a fresh copy, as opposed
to using the <b>rpm -U</b> option.
<li>Historical note to Redhat users: RH releases prior to 8.0 still used Python version
1.5, as many standard scripts depended on it. If you want to run Spyce with
some of the newer Python2 rpms, you will need to change top line of the <font
face=courier>run_spyceCmd.py</font>, <font
face=courier>run_spyceCGI.py</font>, <font
face=courier>run_spyceModpy.py</font> and <font face=courier>verchk.py</font>
scripts, or reconfigure your path so that the default python is the version
that you want. <p>
<big><a name="conf_apache"></a><b>3.10.7. <font color=#ee0000><i>Notes on Apache integration</i></font></b></big><p>


<ul>
<li>If you installed via RPM, Apache is configured to proxy .spy requests to the Spyce webserver. If you are running without the spyce standalone server, comment out those lines in httpd.conf (starting with "Spyce via proxy").
</li>
<li>To avoid confusion, you may wish to change the "root" option in your
<a href="#runtime_common">spyceconf module</a>
to be the same as Apache's DocumentRoot.
<li>You may wish to copy the "Documentation alias" section from spyceApache.conf.
This will allow you to access the spyce documentation and examples
from http://localhost/spyce/, so you can test your install by browsing to
<a href="http://localhost/spyce/examples/hello.spy">http://localhost/spyce/examples/hello.spy</a>.
</ul>
<big><a name="conf_next"></a><b>3.10.8. <font color=#ee0000><i>Starting your first project</i></font></b></big><p>


Spyce provides a simple method to create a new project.
This creates directories for your Spyce project, creates an initial
Spyce <a href="#runtime_common">config file</a>,
and sets up other resources.
<p>
For example, running
<blockquote><font face=courier>python spyceProject.py /var/firstproject</font></blockquote>
results in the following directory structure

<pre class=code>
$ tree /var/firstproject/
    /var/firstproject/
    |-- config.py
    |-- lib
    |-- login_tokens
    `-- www
        |-- _util
        |   |-- form_calendar.gif
        |   `-- form_calendar.js
        |-- index.spy
        |-- parent.spi
        `-- style.css
</pre>

Now you can simply run spyceCmd.py -l --conf /var/firstproject/config.py
and browse to http://localhost:8000/index.spy to verify that it worked.
<p>
Notes:
<ul>
<li>The login_tokens directory is used by the spy:login tags; do not remove it.
<li>The lib/ directory (also initially empty)
is placed on the Python sys.path, meaning you can import any Python module in this
directory from any .spy file. It is good practice to put re-usable code
into .py files in this directory.
</ul>

<big><a name="runtime_prog"></a><b>3.11. <font color=#ee0000>Programmatic Interface</font></b></big><p>


It is also possible to embed Spyce into another program. All you need is to
run or <a href="http://www.python.org/doc/current/ext/embedding.html">embed
</a> a Python interpreter. Although other entry points into the engine code
are possible, the most convenient entry points are in <b>spyce.py</b>:
<ul>
<li> <b>spyceFileHandler</b>( request, response, filename, [sig], [args], [kwargs], [config] ) <br>
</li> <p>
<li> <b>spyceStringHandler</b>( request, response, code, [sig], [args], [kwargs], [config] ) <br>
</li> <p>
</ul> <p>
Either of these functions will execute some Spyce code within the context of some request object and send the output to the corresponding response object. <b>spyceFileHandler</b> gets the Spyce code to be executed from a file, while <b>spyceStringHandler</b> is passed Spyce code in a string.
<big><a name="runtime_prog_basicUsage"></a><b>3.11.1. <font color=#ee0000><i>Basic usage</i></font></b></big><p>


For basic usage, the following arguments need to be understood:
<ul>
<li> <b>request</b> <br>
is an object derived from spyce.spyceRequest, denoting the current HTTP request.
</li> <p>
<li> <b>response</b> <br>
is an object derived from spyce.spyceResponse, denoting the HTTP response resulting from the invocation.
</li> <p>
<li> <b>filename</b> <br>
is the name of a file which contains spyce source code (it will be read, compiled, cached and executed when <font face="courier">spyceFileHandler</font> is called).
</li> <p>
<li> <b>code</b> <br>
is a string which contains spyce source code (it will be executed when <font face="courier">spyceStringHandler</font> is called).<br>
<i>TODO: how is caching handled in this case?</i>
</li> <p>
<li> <b>config</b> <br>
is an object which contains the configuration to be used. The normal usage is to have a configuration file which can be imported as a normal python module. The imported module then passed as <b>conf</b>.
</li>
</ul> <p>

<big><a name="runtime_prog_passingParameters"></a><b>3.11.1. <font color=#ee0000><i>Passing parameters</i></font></b></big><p>


One may wish to also pass a parameter from the calling code into the name space used inside the Spyce code so that it may be accessed from Python Statements, Chunks, Expressions, etcetera. Something analogous to Python's own <font face="courier">execfile</font> built-in function where you can pass a locals and globals dictionary. <p>
Spyce code to be invoked is dealt with similar to a function body, and hence one can send parameters to that "function" upon invocation. The arguments <b>sig</b>, <b>args</b> and <b>kwargs</b> are used to control such parameter passing. With <b>sig</b>, a signature for this external code is specified, with <b>args</b> and <b>kwargs</b> values for the actual arguments are passed. Thus, <b>sig</b> controls what can go into <b>args</b> and <b>kwargs</b>:
<ul>
<li> <b>sig</b> <br>
is a string containing a function signature in usual python syntax, without surrounding brackets.<br>
For example: <font face="courier">'x, y, a=None, b={}'</font>.
</li> <p>
<li> <b>args</b> <br>
is a list of values, each value corresponding to a positional argument specified in <b>sig</b>, in order.
</li> <p>
<li> <b>kwargs</b> <br>
is a dictionary of name to value mappings, its keys should be in the list of keyword argument names specified in <b>sig</b>, its values provide actual values to be passed.
</li> <p>
</ul> <p>

<big><a name="runtime_prog_requestAndResponse"></a><b>3.11.1. <font color=#ee0000><i>Customized Request/Response classes</i></font></b></big><p>


<i>explanation forthcoming; read the code for now, or send an email</i>

<big><a name="runtime_prog_example"></a><b>3.11.1. <font color=#ee0000><i>Example</i></font></b></big><p>


Here's an example that demonstrates such programmatic usage: <p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/programmaticUsage.py</b></font>
</td></tr><tr><td>
  <font face=courier>
    
<style>    
.STRING {
  color: #a0522d;
}
.COMMENT {
  color: #ff7448;
  font-family: serif;
}
.KEYWORD {
  color: #9e79af;
}
.FUNCTION {
  color: #0074ef;
}
</style>
<pre>
<span class="KEYWORD">import</span> <span class="NAME">os</span><span class="NEWLINE">
</span><span class="KEYWORD">import</span> <span class="NAME">spyce</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="COMMENT">#--------------------------------------------------[ a hardcoded fake request ]
</span><span class="KEYWORD">class</span> <span class="FUNCTION">TestRequest</span><span class="OP">(</span><span class="NAME">spyce</span><span class="OP">.</span><span class="NAME">spyceRequest</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">    </span><span class="NAME">environment</span> <span class="OP">=</span> <span class="OP">{</span><span class="STRING">'QUERY_STRING'</span><span class="OP">:</span> <span class="STRING">''</span><span class="OP">,</span><span class="NL">
</span>            <span class="STRING">'REQUEST_METHOD'</span><span class="OP">:</span> <span class="STRING">'get'</span><span class="OP">}</span><span class="NEWLINE">
</span>    <span class="NAME">headers</span> <span class="OP">=</span> <span class="OP">{</span><span class="OP">}</span><span class="NEWLINE">
</span>    <span class="NL">
</span>    <span class="KEYWORD">def</span> <span class="FUNCTION">env</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="NAME">name</span><span class="OP">=</span><span class="NAME">None</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="KEYWORD">if</span> <span class="KEYWORD">not</span> <span class="NAME">name</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">            </span><span class="KEYWORD">return</span> <span class="NAME">self</span><span class="OP">.</span><span class="NAME">environment</span><span class="NEWLINE">
</span>        <span class="DEDENT"></span><span class="KEYWORD">return</span> <span class="NAME">self</span><span class="OP">.</span><span class="NAME">environment</span><span class="OP">[</span><span class="NAME">name</span><span class="OP">]</span><span class="NEWLINE">
</span>    <span class="NL">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">getHeader</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="NAME">type</span><span class="OP">=</span><span class="NAME">None</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="KEYWORD">return</span> <span class="NAME">self</span><span class="OP">.</span><span class="NAME">headers</span><span class="OP">[</span><span class="NAME">type</span><span class="OP">]</span><span class="NEWLINE">
</span>    <span class="NL">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">getServerID</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="NAME">os</span><span class="OP">.</span><span class="NAME">getpid</span><span class="OP">(</span><span class="OP">)</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="NL">
</span><span class="COMMENT">#--------------------------------------------------[ a hardcoded fake response ]
</span><span class="DEDENT"></span><span class="DEDENT"></span><span class="KEYWORD">class</span> <span class="FUNCTION">TestResponse</span><span class="OP">(</span><span class="NAME">spyce</span><span class="OP">.</span><span class="NAME">spyceResponse</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">    </span><span class="NAME">returncode</span> <span class="OP">=</span> <span class="NAME">spyce</span><span class="OP">.</span><span class="NAME">spyceResponse</span><span class="OP">.</span><span class="NAME">RETURN_OK</span><span class="NEWLINE">
</span>    <span class="NAME">out</span> <span class="OP">=</span> <span class="STRING">''</span><span class="NEWLINE">
</span>    <span class="NAME">err</span> <span class="OP">=</span> <span class="STRING">''</span><span class="NEWLINE">
</span>    <span class="NAME">headers</span> <span class="OP">=</span> <span class="OP">{</span><span class="OP">}</span><span class="NEWLINE">
</span>    <span class="KEYWORD">def</span> <span class="FUNCTION">write</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="NAME">s</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">out</span> <span class="OP">=</span> <span class="NAME">self</span><span class="OP">.</span><span class="NAME">out</span><span class="OP">+</span><span class="NAME">s</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">writeErr</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="NAME">s</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">err</span> <span class="OP">=</span> <span class="NAME">self</span><span class="OP">.</span><span class="NAME">err</span><span class="OP">+</span><span class="NAME">s</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">close</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="KEYWORD">pass</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">clear</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">out</span> <span class="OP">=</span> <span class="STRING">''</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">sendHeaders</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="KEYWORD">pass</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">clearHeaders</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">headers</span> <span class="OP">=</span> <span class="OP">{</span><span class="OP">}</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">setContentType</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="NAME">content_type</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">headers</span><span class="OP">[</span><span class="STRING">'content-type'</span><span class="OP">]</span> <span class="OP">=</span> <span class="NAME">content_type</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">setReturnCode</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="NAME">code</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">returncode</span> <span class="OP">=</span> <span class="NAME">code</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">addHeader</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="NAME">type</span><span class="OP">,</span> <span class="NAME">data</span><span class="OP">,</span> <span class="NAME">replace</span><span class="OP">=</span><span class="NUMBER">0</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="NAME">self</span><span class="OP">.</span><span class="NAME">headers</span><span class="OP">[</span><span class="NAME">type</span><span class="OP">]</span> <span class="OP">=</span> <span class="NAME">data</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">flush</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">,</span> <span class="OP">*</span><span class="NAME">args</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="KEYWORD">pass</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">def</span> <span class="FUNCTION">unbuffer</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">        </span><span class="KEYWORD">pass</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="NL">
</span><span class="COMMENT">#--------------------------------------------------[ invoking Spyce code ]
</span><span class="DEDENT"></span><span class="DEDENT"></span><span class="KEYWORD">import</span> <span class="NAME">spyceConfig</span><span class="NEWLINE">
</span>    <span class="NL">
</span><span class="NAME">req</span> <span class="OP">=</span> <span class="NAME">TestRequest</span><span class="OP">(</span><span class="OP">)</span><span class="NEWLINE">
</span><span class="NAME">resp</span> <span class="OP">=</span> <span class="NAME">TestResponse</span><span class="OP">(</span><span class="OP">)</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="NAME">spyceCode</span>  <span class="OP">=</span> <span class="STRING">'Hello, the following names are defined: "[[print dir(),]]", and '</span><span class="NEWLINE">
</span><span class="NAME">spyceCode</span> <span class="OP">+=</span> <span class="STRING">'these were the parameters passed: [[print (a, b, c, d)]]\n'</span><span class="OP">,</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="NAME">spyce</span><span class="OP">.</span><span class="NAME">spyceStringHandler</span><span class="OP">(</span><span class="NL">
</span>             <span class="NAME">req</span><span class="OP">,</span><span class="NL">
</span>             <span class="NAME">resp</span><span class="OP">,</span><span class="NL">
</span>             <span class="NAME">spyceCode</span><span class="OP">,</span><span class="NL">
</span>             <span class="NAME">sig</span><span class="OP">=</span><span class="STRING">'a, b, c="asd", d=None'</span><span class="OP">,</span><span class="NL">
</span>             <span class="NAME">args</span><span class="OP">=</span><span class="OP">(</span><span class="NUMBER">1</span><span class="OP">,</span> <span class="STRING">'two'</span><span class="OP">)</span><span class="OP">,</span><span class="NL">
</span>             <span class="NAME">kwargs</span><span class="OP">=</span><span class="OP">{</span><span class="STRING">'c'</span><span class="OP">:</span> <span class="STRING">'aa'</span><span class="OP">}</span><span class="OP">,</span><span class="NL">
</span>             <span class="NAME">config</span><span class="OP">=</span><span class="NAME">spyceConfig</span><span class="OP">)</span><span class="NEWLINE">
</span><span class="KEYWORD">print</span> <span class="NAME">resp</span><span class="OP">.</span><span class="NAME">err</span><span class="NEWLINE">
</span><span class="KEYWORD">print</span> <span class="NAME">resp</span><span class="OP">.</span><span class="NAME">out</span><span class="NEWLINE">
</span><span class="ENDMARKER"></span>
</pre>
    
  </font>
</td></tr></table>



<p><big><a name="add"></a><b>4. <font color=#ee0000>ADDENDA</font></b></big><p>


List of appendices:
<ul>
<li><a href="#add_perf">Performance</a> - Some throughput
micro-benchmarks</li><p>
<li><a href="#add_history">History</a> - The brief history
of Spyce</li><p>
</ul>
<big><a name="add_perf"></a><b>4.1. <font color=#ee0000>Performance</font></b></big><p>


Although flexibility usually outweighs raw performance in the choice of
technology, it is nice to know that the technology that you have chosen is not
a resource hog, and can scale to large production sites. The current Spyce
implementation is comparable to its cousin technologies: JSP, PHP and ASP. We
ran a micro-benchmark using <b>hello.spy</b> and equivalents. All benchmark
files are available in the <font face=courier>misc/benchmark</font>
directory.<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/hello.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#229922">&lt;spy:parent title=&quot;Hello&quot; /&gt;</font>
<font color="#0000CC">[[ import spyce ]]</font>

Hello from Spyce version 
<font color="#CC0000">[[= spyce.__version__ ]]</font>!
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/hello.spy">Run this code</a></b>
    </font>
</td></tr></table>
<p>
Spyce was measured under CGI, FCGI, mod_python and proxy configurations. For
calibration the static HTML, CGI-C, CGI-Python and FCGI-Python tests were
performed. In the case of CGI-C, the request is handled by a compiled C
program with the appropriate printf statements. In the case of CGI-Python, we
have an executable Python script with the appropriate print statements.
FCGI-Python is a similar script that is FCGI enabled. ASP was measured on a
different machine, only to satisfy curiosity; those results are omitted. <p>
<table border=1 align=center>
<tr>
<td bgcolor="#cccccc"><font face="arial, helvetica" size="-1">Configuration</font></td>
<td bgcolor="#cccccc"><font face="arial, helvetica" size="-1">Hello world!</font></td>
</tr>
<tr>
<td><font face="arial, helvetica" size="-1"><b>Spyce-modpython</b></font></td>
<td align=right><font face="arial, helvetica" size="-1"><b>250</b></font></td>
</tr>