doc-single.html

</span><span class="INDENT">    </span><span class="KEYWORD">if</span> <span class="NAME">key</span> <span class="KEYWORD">in</span> <span class="NAME">toClean</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">      </span><span class="NAME">d</span><span class="OP">[</span><span class="NAME">key</span><span class="OP">]</span> <span class="OP">=</span> <span class="OP">[</span><span class="NAME">Html</span><span class="OP">.</span><span class="NAME">clean</span><span class="OP">(</span><span class="NAME">s</span><span class="OP">)</span> <span class="KEYWORD">for</span> <span class="NAME">s</span> <span class="KEYWORD">in</span> <span class="NAME">d</span><span class="OP">[</span><span class="NAME">key</span><span class="OP">]</span><span class="OP">]</span><span class="NEWLINE">
</span>    <span class="DEDENT"></span><span class="KEYWORD">else</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">      </span><span class="NAME">d</span><span class="OP">[</span><span class="NAME">key</span><span class="OP">]</span> <span class="OP">=</span> <span class="OP">[</span><span class="NAME">Html</span><span class="OP">.</span><span class="NAME">escape</span><span class="OP">(</span><span class="NAME">s</span><span class="OP">)</span> <span class="KEYWORD">for</span> <span class="NAME">s</span> <span class="KEYWORD">in</span> <span class="NAME">d</span><span class="OP">[</span><span class="NAME">key</span><span class="OP">]</span><span class="OP">]</span><span class="NEWLINE">
</span><span class="DEDENT"></span><span class="DEDENT"></span><span class="DEDENT"></span><span class="ENDMARKER"></span>
</pre>
    
  </font>
</td></tr></table>

<p>
<b>The request module provides the following methods:</b>
<ul>
<li><b>login_id</b>: <br>
Returns the id generated by your validator function if the user has logged in
via spy:login or spy:login_required, or None if the user is unvalidated. (See the
<a href="#tag_core">core tag library</a> for details on
the login tags.)
<li><b>uri</b>( [component] ): <br> Returns the request URI, or some
component thereof. If the optional <b>component</b> parameter is specified,
it should be one of the following strings:
<font face=courier>'scheme'</font>,
<font face=courier>'location'</font>,
<font face=courier>'path'</font>,
<font face=courier>'parameters'</font>,
<font face=courier>'query'</font> or
<font face=courier>'fragment'</font>.
</li><p>
<li><b>method</b>(): <br> Returns request method type (GET, POST,
...)</li><p>
<li><b>query</b>(): <br> Returns the request query string</li><p>
<li><b>get</b>( [name], [default], [ignoreCase] ): <br> Returns request GET
information. If <b>name</b> is specified then a single list of values is
returned if the parameter exists, or <b>default</b>, which defaults to an
empty list,
if the parameter does not exist. Parameters without values are skipped,
though empty string values are allowed. If name is omitted, then a
dictionary of lists is returned. If <b>ignoreCase</b> is true, then the
above behaviour is performed in a case insensitive manner (all parameters
are treated as lowercase). </li><p>
<li><b>get1</b>( [name], [default], [ignoreCase] ): <br> Returns request GET
information, similarly to (though slightly differently from) the function
above. If <b>name</b> is specified then a single string is returned if the
parameter exists, or <b>default</b>, which default to None, if the parameter
does not exist. If there is more than one value for a parameter, then only
one is returned. Parameters without values are skipped, though empty string
values are allowed. If name is omitted, then a dictionary of strings is
returned. If the optional <b>ignoreCase</b> flag is true, then the above
behaviour is performed in a case insensitive manner (all parameters are
treated as lowercase). </li><p>
<li><b>post</b>( [name], [default], [ignoreCase] ): <br> Returns request
POST information. If <b>name</b> is specified then a single list of values
is returned if the parameter exists, or <b>default</b>, which defaults to
an empty list, if the parameter does not exist. Parameters without values are
skipped, though empty string values are allowed. If name is omitted, then a
dictionary of lists is returned. If <b>ignoreCase</b> is true, then the
above behaviour is performed in a case insensitive manner (all parameters
are treated as lowercase). This function understands form information
encoded either as 'application/x-www-form-urlencoded' or
'multipart/form-data'. Uploaded file parameters are not included in this
dictionary; they can be accessed via the file method. </li><p>
<li><b>post1</b>( [name], [default], [ignoreCase] ): <br> Returns request
POST information, similarly to (though slightly differently from) the
function above. If <b>name</b> is specified then a single string is returned
if the parameter exists, or <b>default</b>, which defaults to None, if the
parameter does not exist. If there is more than one value for a parameter,
then only one is returned. Parameters without values are skipped, though
empty string values are allowed. If name is omitted, then a dictionary of
strings is returned. If the optional <b>ignoreCase</b> flag is true, then
the above behaviour is performed in a case insensitive manner (all
parameters are treated as lowercase). This function understands form
information encoded either as 'application/x-www-form-urlencoded' or
'multipart/form-data'. Uploaded file parameters are not included in this
dictionary; they can be accessed via the file method. </li><p>
<li><b>file</b>( [name], [ignoreCase] ): <br> Returns files POSTed in the
request. If <b>name</b> is specified then a single cgi.FieldStorage class is
returned if such a file parameter exists, otherwise None. If name is
omitted, then a dictionary of file entries is returned. If the optional
<b>ignoreCase</b> flag is true, then the above behaviour is performed in a
case insensitive manner (all parameters are treated as lowercase). The
interesting fields of the FieldStorage class are: <p>
<ul>
<li><b>name:</b> the field name, if specified; otherwise None</li>
<li><b>filename:</b> the filename, if specified; otherwise None; this is
the client-side filename, not the filename in which the content is stored
- a temporary file you don't deal with
<li><b>value:</b> the value as a string; for file uploads, this
transparently reads the file every time you request the value
<li><b>file:</b> the file(-like) object from which you can read the data;
None if the data is stored a simple string
<li><b>type:</b> the content-type, or None if not specified
<li><b>type_options:</b> dictionary of options specified on the
content-type line
<li><b>disposition:</b> content-disposition, or None if not specified
<li><b>disposition_options:</b> dictionary of corresponding options
<li><b>headers:</b> a dictionary(-like) object (sometimes rfc822.Message
or a subclass thereof) containing *all* headers
</ul><p>
<li><b>__getitem__</b>( key ): <br> The request module can be used as a
dictionary: i.e. request['foo']. This method first calls the get1() method,
then the post1() method and lastly the file() method trying to find the
first non-None value to return. If no value is found, then this method
returns None. Note: Throwing an exception seemed too strong a semantics, and
so this is a break from Python. One can also iterate over the request
object, as if over a dictionary of field names in the get1 and post1
dictionaries. In the case of overlap, the get1() dictionary takes
precedence. </li><p>
<li><b>getpost</b>( [name], [default], [ignoreCase] ): <br> Using given
parameters, return get() result if not None, otherwise return post() result
if not None, otherwise <b>default</b>. </li><p>
<li><b>getpost1</b>( [name], [default], [ignoreCase] ): <br> Using given
parameters, return get1() result if not None, otherwise return post1()
result if not None, otherwise <b>default</b>. </li><p>
<li><b>postget</b>( [name], [default], [ignoreCase] ): <br> Using given
parameters, return post() result if not None, otherwise return get() result
if not None, otherwise <b>default</b>. </li><p>
<li><b>postget1</b>( [name], [default], [ignoreCase] ): <br> Using given
parameters, return post1() result if not None, otherwise return get1()
result if not None, otherwise <b>default</b>. </li><p>
<li><b>env</b>( [name], [default] ): <br> Returns a dictionary with CGI-like
environment information of this request. If <b>name</b> is specified then a
single entry is returned if the parameter exists, otherwise <b>default</b>,
which defaults to None, if omitted. </li><p>
<li><b>getHeader</b>( [type] ): <br> Return a specific header sent by the
browser. If optional <b>type</b> is omitted, a dictionary of all headers is
returned.</li><p>
<li><b>filename</b>( [path] ): <br> Return the Spyce filename of the request
currently being processed. If an optional <b>path</b> parameter is provided,
then that path is made relative to the Spyce filename of the request
currently being processed. </li><p>
<li><b>stack</b>( [i] ): <br> Returns a stack of files processed by the
Spyce runtime. If <b>i</b> is provided, then a given frame is returned,
with negative numbers wrapping from the back as per Python convention.
The first (index zero) item on the stack is the filename
corresponding to the URL originally requested. The last (index -1) item
on the stack is the current filename being processed. Items are added
to the stack by <a href="#mod_include">includes</a>,
<a href="#lang_lambda">Spyce lambdas</a>, and
<a href="#mod_redirect">internal redirects</a>.<p>
<li><b>default</b>( value, value2 ): <br> (convenience method) Return
<b>value</b> if it is not None, otherwise return <b>value2</b>. </li><p>
</ul>
The example below presents the results of all the method calls list above. Run
it to understand the information available. <p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/request.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b>&lt;html&gt;&lt;body&gt;
  Using the Spyce request object, we can obtain 
  information sent along with the request. The 
  table below shows some request methods and their 
  return values. Use the form below to post form 
  data via GET or POST. &lt;br&gt;
  &lt;hr&gt;
  <font color="#ff7448">[[-- input forms --]]</font>
  &lt;form action=&quot;<font color="#CC0000">[[=request.uri('path')]]</font>&quot; method=get&gt;
    get: &lt;input type=text name=name&gt;
    &lt;input type=submit value=ok&gt;
  &lt;/form&gt;
  &lt;form action=&quot;<font color="#CC0000">[[=request.uri('path')]]</font>&quot; method=post&gt;
    post: &lt;input type=text name=name&gt;
    &lt;input type=submit value=ok&gt;
  &lt;/form&gt;
  &lt;hr&gt;
  <font color="#ff7448">[[-- tabulate response information --]]</font>
  &lt;table border=1&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;b&gt;Method&lt;/b&gt;&lt;/td&gt;
      &lt;td&gt;&lt;b&gt;Return value&lt;/b&gt;&lt;/td&gt;
    &lt;/tr&gt;
    <font color="#0000CC">[[ for method in ['uri()', 'uri(&quot;path&quot;)',
      'uri(&quot;query&quot;)', 'method()','query()',
      'get()','get1()', 'post()','post1()',
      'getHeader()','env()', 'filename()']: { 
    ]]</font>
      &lt;tr&gt;
        &lt;td valign=top&gt;request.<font color="#CC0000">[[=method]]</font>&lt;/td&gt;
        &lt;td&gt;<font color="#CC0000">[[=eval('request.%s' % method)]]</font>&lt;/td&gt;
      &lt;/tr&gt;
    <font color="#0000CC">[[ } ]]</font>
  &lt;/table&gt;
&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/request.spy">Run this code</a></b>
    </font>
</td></tr></table>
<p>
Lastly, the following example shows how to deal with uploaded files. <p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/fileupload.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">[[\ 
if request.post('ct'):
  response.setContentType(request.post1('ct'))
  if request.file('upfile')!=None:
    response.write(request.file('upfile').value)
  else:
    print 'file not properly uploaded'
  raise spyceDone
]]</font>
&lt;html&gt;&lt;body&gt;
  Upload a file and it will be sent back to you.&lt;br&gt;
  <font color="#ff7448">[[-- input forms --]]</font>
  &lt;hr&gt;
  &lt;table&gt;
    &lt;form action=&quot;<font color="#CC0000">[[=request.uri('path')]]</font>&quot; method=post 
        enctype=&quot;multipart/form-data&quot;&gt;
      &lt;tr&gt;
        &lt;td&gt;file:&lt;/td&gt;
        &lt;td&gt;&lt;input type=file name=upfile&gt;&lt;/td&gt;
      &lt;/tr&gt;&lt;tr&gt;
        &lt;td&gt;content-type:&lt;/td&gt;
        &lt;td&gt;&lt;input type=text name=ct value=&quot;text/html&quot;&gt;&lt;/td&gt;
      &lt;/tr&gt;&lt;tr&gt;
        &lt;td&gt;&lt;input type=submit value=ok&gt;&lt;/td&gt;
      &lt;/tr&gt;
    &lt;/form&gt;
  &lt;/table&gt;
&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/fileupload.spy">Run this code</a></b>
    </font>
</td></tr></table>
 <p>
<big><a name="mod_response"></a><b>3.8.3. <font color=#ee0000><i>Response (implicit)</i></font></b></big><p>


Like the request module, the response module is also loaded implicitly into every
Spyce environment. It provides the following methods:
<ul>
<li><b>write</b>( string ): <br> Sends a <b>string</b> to the client. All
writes are buffered by default and sent at the end of Spyce processing to
allow appending headers, setting cookies and exception handling. Note that
using the <font face="courier">print</font> statement is often easier, and
<a href="#mod_stdout">stdout</a> is implicitly redirected
to the browser. </li> <p>
<li><b>writeln</b>( string ): <br> Sends a <b>string</b> to the client, and
appends a newline. </li><p>
<li><b>writeStatic</b>( string ): <br> All static HTML <b>strings</b> are
emitted to the client via this method, which (by default) simply calls
write(). This method is <i>not</i> commonly invoked by the user. </li><p>
<li><b>writeExpr</b>( object ): <br> All expression results are emitted to
the client via this method, which (by default) calls write() with the str()
of the result <b>object</b>. This method is <i>not</i> commonly invoked by
the user. </li><p>
<li><b>clear</b>( ): Clears the output buffer. </li> <p>
<li><b>flush</b>( ): Sends buffered output to the client immediately. This
is a blocking call, and can incur a performance hit.</li> <p>
<li><b>setContentType</b>( contentType ): <br> Sets the MIME <b>content
type</b> of the response. </li> <p>
<li><b>setReturnCode</b>( code ): <br> Set the HTTP return code for this
response. This <b>return code</b> may be overriden if an error occurs or by
functions in other modules (such as redirects). </li> <p>
<li><b>addHeader</b>( type, data, [replace] ): <br> Adds the header line
"<font face=courier>type:&nbsp;data</font>" to the outgoing response. The
optional <b>replace</b> flag determines whether any previous headers of the
same type are first removed. </li><p>
<li><b>unbuffer</b>(): <br> Turns off buffering on the output stream. In
other words, each write is followed by a flush(). An unbuffered output
stream should be used only when sending large amounts of data (ie. file
transfers) that would take up server memory unnecessarily, and involve
consistently large writes. Note that using an unbuffered response stream
will not allow the output to be cleared if an exception occurs. It will also
immediately send any headers. </li><p>
<li><b>isCancelled</b>(): <br> Returns true if it has been detected that the
client is no longer connected. This flag will turn on, and remain on, after
the first client output failure. However, the detection is best-effort, and
may never turn on in certain configurations (such as CGI) due to buffering.
</li><p>
<li><b>timestamp</b>( [t] ):<br> Timestamps the response with an HTTP
<font face=courier>Date:</font> header, using the optional <b>t</b>
parameter, which may be either be the number of seconds since the epoch
(see Python <a
href="http://www.python.org/doc/current/lib/module-time.html">time</a>
module), or a properly formatted HTTP date string. If t is omitted,
the current time is used. </li> <p>
<li><b>expires</b>( [t] ):<br> Sets the expiration time of the
response with an HTTP <font face=courier>Expires:</font> header, using the
optional <b>t</b> parameter, which may be either the number of seconds
since the epoch (see Python <a
href="http://www.python.org/doc/current/lib/module-time.html">time</a>
module), or a properly formatted HTTP date string. If t is omitted,
the current time is used. </li> <p>
<li><b>expiresRel</b>( [secs] ):<br> Sets the expiration time of the
response <i>relative to the current time</i> with an HTTP <font
face=courier>Expires:</font> header. The optional <b>secs</b> (which may
also be negative) indicates the number of seconds to add to the current time
to compute the expiration time. If secs is omitted, it defaults to zero.
</li> <p>
<li><b>lastModified</b>( [t] ):<br> Sets the last modification time of
the response with an HTTP <font face=courier>Last-Modified:</font> header,
using the optional <b>t</b> parameter, which can be either the number
of seconds since the epoch (see Python <a
href="http://www.python.org/doc/current/lib/module-time.html">time</a>
module), or a properly formatted HTTP date string, or None indicating the
current time. If t is omitted, this function will default to the last
modification time of the Spyce file for this request, and raise an exception
if this time can not be determined. Note that, as per the HTTP
specification, you should not set a last modification time that is beyond
the response timestamp.</li> <p>
<li><b>uncacheable</b>():<br> Sets the HTTP/1.1 <font
face=courier>Cache-Control:</font> and HTTP/1.0 <font
face=courier>Pragma:</font> headers to inform clients and proxies that this
content should not be cached. </li> <p>
</ul>
The methods are self-explanatory. One of the more interesting things that one could do is
to emit non-HTML content types. The example below emits the Spyce logo as a GIF.<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/gif.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">[[.import name=include ]]</font>
<font color="#0000CC">[[\
  # Spyce can also generate other content types
  # The following code displays the Spyce logo
  response.setContentType('image/gif')
  import os.path, spyce
  path = os.path.join(spyce.getServer().config.SPYCE_HOME, 'www', 'spyce.gif')
  response.write(include.dump(path, 1))
  raise spyceDone
]]</font>
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/gif.spy">Run this code</a></b>
    </font>
</td></tr></table>
 <p>
<big><a name="mod_redirect"></a><b>3.8.4. <font color=#ee0000><i>Redirect</i></font></b></big><p>


The redirect module allows requests to be redirected to different pages, by
providing the following methods:
<ul>
<li><b>internal</b>( uri ): <br> Performs an internal redirect. All
processing on the current page ends, the output buffer is cleared and
processing continues at the named <b>uri</b>.
The browser URI remains
unchanged, and does not realise that a redirect has even occurred during
processing. </li><p>
<li><b>external</b>( uri, [permanent] ): <br> Performs an external redirect
using the HTTP Location header to a new <b>uri</b>. <b>Processing of the
current file continues</b> unless you raise spyceDone,
but the content is ignored (ie. the buffer is
cleared at the end). The status of the document is set to 301&nbsp;MOVED
PERMANENTLY or 302&nbsp;MOVED TEMPORARILY, depending on the <b>permanent</b>
boolean parameter, which defaults to false or temporary. The redirect
document is sent to the browser, which requests the new relative uri.
</li><p>
<li><b>externalRefresh</b>( uri, [seconds] ): <br> Performs an external
redirect using the HTTP Refresh header a new <b>uri</b>. Processing of the
current file continues, and will be displayed on the browser as a regular
document. Unless interrupted by the user, the browser will request the new
URL after the specified number of <b>seconds</b>, which defaults to zero if
omitted. Many websites use this functionality to show some page, while a
file is being downloaded. To do this, one would show the page using Spyce,
and redirect with an externalRefresh to the download URI. Remember to set
the <font face=courier>Content-Type</font> on the target download file page
to be something that the browser can not display, only download. </li><p>
</ul>
The example below, shows the possible redirects in use:<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/redirect.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">[[.import name=redirect]]</font>
&lt;html&gt;&lt;body&gt;
  <font color="#0000CC">[[ type = request['type']
     url = request['url']
     if url and not type: {
       ]]</font> 
       &lt;font color=red&gt;&lt;b&gt;
         please select a redirect type
       &lt;/b&gt;&lt;/font&gt;&lt;br&gt; 
       <font color="#0000CC">[[
     }
     if type and url: {
       if type=='internal': redirect.internal(url)
       if type=='external': redirect.external(url)
       if type=='externalRefresh': redirect.externalRefresh(url, 3)
       ]]</font> Received POST info: <font color="#CC0000">[[=request.post1()]]</font> <font color="#0000CC">[[
     }
  ]]</font>
  &lt;form action=&quot;<font color="#CC0000">[[=request.uri('path')]]</font>&quot; method=post&gt;
    Redirection url:
    &lt;input type=text name=url value=hello.spy&gt;&lt;br&gt;
    Redirection type:
    &lt;table border=0&gt;
      &lt;tr&gt;&lt;td&gt;
        &lt;input type=radio name=type value=internal&gt;
        internal
      &lt;/td&gt;&lt;/tr&gt;
      &lt;tr&gt;&lt;td&gt;
        &lt;input type=radio name=type value=external&gt;
        external
      &lt;/td&gt;&lt;/tr&gt;
      &lt;tr&gt;&lt;td&gt;
        &lt;input type=radio name=type value=externalRefresh&gt;
        externalRefresh (3 seconds)
      &lt;/td&gt;&lt;/tr&gt;
    &lt;/table&gt;
    &lt;input type=submit value=redirect&gt;
  &lt;/form&gt;
&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/redirect.spy">Run this code</a></b>
    </font>
</td></tr></table>
 <p>
<big><a name="mod_cookie"></a><b>3.8.5. <font color=#ee0000><i>Cookie</i></font></b></big><p>


This module provides cookie functionality. Its methods are:
<ul>
<li><b>get</b>( [key] ): <br> Return a specific cookie string sent by the
browser. If the optional cookie <b>key</b> is omitted, a dictionary of all
cookies is returned. The cookie module may also be accessed as an
associative array to achieve the same result as calling: namely, <font
face=courier>cookie['foo']</font> and <font
face=courier>cookie.get('foo')</font> are equivalent. </li><p>
<li><b>set</b>( key, value, [expire], [domain], [path], [secure] ): <br>
Sends a cookie to the browser. The cookie will be sent back on
<i>subsequent</i> requests and can be retreived using the get function. The
<b>key</b> and <b>value</b> parameters are required; the rest are optional.
The <b>expire</b> parameter determines how long this cookie information will
remain valid. It is specified in seconds from the current time. If expire is
omitted, no expiration value will be provided along with the cookie header,
meaning that the cookie will expire when the browser is closed. The
<b>domain</b> and <b>path</b> parameters specify when the cookie will get
sent; it will be restricted to certain document paths at certain domains,
based on the cookie standard. If these are omitted, then path and/or domain
information will not be sent in the cookie header. Lastly, the <b>secure</b>
parameter, which defaults to false if omitted, determines whether the cookie
information can be sent over an HTTP connection, or only via HTTPS. </li><p>
<li><b>delete</b>( key ): <br> Send a cookie delete header to the browser to
delete the <b>key</b> cookie. The same may be achieved by: <font
face=courier>del cookie[key]</font>. </li><p>
</ul>
The example below shows to manage browser cookies.<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/cookie.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">[[.import name=cookie]]</font>
&lt;html&gt;&lt;body&gt;
  Managing cookies is simple. Use the following forms 
  to create and destroy cookies. Remember to refresh 
  once, because the cookie will only be transmitted on 
  the &lt;i&gt;following&lt;/i&gt; request.&lt;br&gt;
  <font color="#ff7448">[[-- input forms --]]</font>
  &lt;hr&gt;
  &lt;form action=&quot;<font color="#CC0000">[[=request.uri('path')]]</font>&quot; method=post&gt;
    &lt;table&gt;&lt;tr&gt;
      &lt;td align=right&gt;Cookie name:&lt;/td&gt;
      &lt;td&gt;&lt;input type=text name=name&gt;&lt;/td&gt;
      &lt;td&gt;(required)&lt;/td&gt;
    &lt;/tr&gt;&lt;tr&gt;
      &lt;td align=right&gt;value:&lt;/td&gt;
      &lt;td&gt;&lt;input type=text name=value&gt;&lt;/td&gt;
      &lt;td&gt;(required for set)&lt;/td&gt;
    &lt;/tr&gt;&lt;tr&gt;
      &lt;td align=right&gt;expiration:&lt;/td&gt;
      &lt;td&gt;&lt;input type=text name=exp&gt; seconds.&lt;/td&gt;
      &lt;td&gt;(optional)&lt;/td&gt;
    &lt;/tr&gt;&lt;tr&gt;
      &lt;td colspan=3&gt;
        &lt;input type=submit name=operation value=set&gt;
        &lt;input type=submit name=operation value=delete&gt;
        &lt;input type=submit name=operation value=refresh&gt;
      &lt;/td&gt;
    &lt;/tr&gt;&lt;/table&gt;
  &lt;/form&gt;
  &lt;hr&gt;
  <font color="#ff7448">[[-- show cookies --]]</font>
  Cookies: <font color="#CC0000">[[=len(cookie.get().keys())]]</font>&lt;br&gt;
  &lt;table&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;b&gt;name&lt;/b&gt;&lt;/td&gt;
      &lt;td&gt;&lt;b&gt;value&lt;/b&gt;&lt;/td&gt;
    &lt;/tr&gt;
    <font color="#0000CC">[[for c in cookie.get().keys(): {]]</font>
      &lt;tr&gt;
        &lt;td&gt;<font color="#CC0000">[[=c]]</font>&lt;/td&gt;
        &lt;td&gt;<font color="#CC0000">[[=cookie.get(c)]]</font>&lt;/td&gt;
      &lt;/tr&gt;
    <font color="#0000CC">[[ } ]]</font>
  &lt;/table&gt;
  <font color="#ff7448">[[-- set cookies --]]</font>
  <font color="#0000CC">[[\
    operation = request.post('operation')
    if operation:
      operation = operation[0]
      name = request.post('name')[0]
      value = request.post('value')[0]
      if operation == 'set' and name and value:
        cookie.set(name, value)
      if operation == 'delete' and name:
        cookie.delete(name)
  ]]</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/cookie.spy">Run this code</a></b>
    </font>
</td></tr></table>
 <p>
<big><a name="mod_session"></a><b>3.8.6. <font color=#ee0000><i>Session</i></font></b></big><p>


Sessions allow information to be efficiently passed from one user request to
the next via some browser mechanism: get, post or cookie. Potentially large or
sensitive information is stored at the server, and only a short identifier is
sent to the client to be returned on callback. Sessions are often used to
create sequences of stateful pages that represent an application or work-flow.
<p>
This module automates sessioning for a Spyce web site. It emulates
a dictionary specific to each user (really each browser) accessing
your web site. You simply use session as if it were a dictionary
variable, and its contents automatically change depending upon the
user calling the page. For example:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/session2.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">[[.import name=session ]]</font>
<font color="#0000CC">[[\
  session['visited'] = session.get('visited', 0) + 1
]]</font>

<font color="#229922">&lt;spy:parent title=&quot;Session example&quot; /&gt;</font>

You visited us <font color="#CC0000">[[= session['visited'] ]]</font> times.
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/session2.spy">Run this code</a></b>
    </font>
</td></tr></table>

<p>
In the example above, the 'visited' key would now be valid for
all pages on your site, until the session expires.
<p>
<big>Global session options</big>
<p>
These options are configured only in the Spyce config file:
<ul>
<li><b>session_store</b>: declares the backing storage for session
information. It should be either <font
face=courier>session.DbmStore(path)</font> or <font
face=courier>session.MemoryStore()</font>. In-memory sessions storage is
faster, but volatile, and does not work in multi-process server
configurations. Advanced users are welcome to create their own storage
manager, by subclassing <b>session.SessionStore</b>. </li>
</ul>
Advanced users can create their own storage manager by subclassing
session.SessionStore.
<p>
<big>Per-session options</big>
<p>
These options are set in the Spyce config file, but may be overridden
at module-import time on a per-page basis:
<ul>
<li><b>session_path</b>: the default path to attach the session to.
This refers to
cookie semantics. For example, if the path is /myapp, the session
will only be valid under /myapp pages (and below). The default is
'/', which means the session is valid site-wide.
<li><b>session_expire</b>: the number of seconds the session is good for.
The default is one day.
<p>
You should clean up expired session state periodically. The easiest way
is to schedule session.clean_store every day or so in your config file:

<pre class=code>
import session, scheduler
scheduler.schedule_daily(0, 0, session.clean_store)
</pre>

<p>
(Note: for backwards compatibility, there is also a module called "session1."
New code should simply use the module described here.)
<big><a name="mod_pool"></a><b>3.8.7. <font color=#ee0000><i>Pool</i></font></b></big><p>


The pool module provides support for server-pooled variables. That is support
for variables whose lifetime begins when declared, and ends when explicitly
deleted or when the server dies. These variables are often useful for caching
information that would be expensive to
compute from scratch for each request. Another common use of pool variables is to store
file- or memory-based lock objects for concurrency control. A pooled variable
can hold any Python value. <p>
The pool module may be accessed as a regular dictionary, supporting the usual
<font face=courier>get</font>, <font face=courier>set</font>, <font
face=courier>delete</font>, <font face=courier>has_key</font>, <font
face=courier>keys</font>, <font face=courier>values</font> and <font
face=courier>clear</font> operations.
<p>
The example below shows how the module is used:<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/pool.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">[[.import names=&quot;pool&quot;]]</font>
&lt;html&gt;&lt;body&gt;
  The pool module supports long-lived server-pooled objects,&lt;br&gt;
  useful for database connections, and other variables&lt;br&gt;
  that are expensive to compute.&lt;br&gt;
  <font color="#0000CC">[[\
    if 'foo' in pool:
      print 'Pooled object foo EXISTS.'
    else:
      pool['foo'] = 1
      print 'Pooled object foo CREATED.'
  ]]</font>
  &lt;br&gt;
  Value: <font color="#CC0000">[[=pool['foo'] ]]</font> &lt;p&gt;
&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/pool.spy">Run this code</a></b>
    </font>
</td></tr></table>
 <p>
<p>
Pool performance suffers when not used with the Spyce webserver in
threaded concurrency mode; Spyce has to un/pickle the shared pool with
each request since there is no single long-lived process that can keep
the data in-memory.
<big><a name="mod_transform"></a><b>3.8.8. <font color=#ee0000><i>Transform</i></font></b></big><p>


The transform module contains useful text transformation functions, commonly
used during web-page generation. <p>
<ul>
<li><b>html_encode</b>( string, [also] ): <br> Returns a HTML-encoded
<b>string</b>, with special characters replaced by entity references as
defined in the HTML 3.2 and 4 specifications. The optional <b>also</b>
parameter can be used to encode additional characters. </li><p>
<li><b>url_encode</b>( string, ): <br> Returns an URL-encoded <b>string</b>,
with special characters replaced with %XX equivalents as defined by the URI
RFC document. </li><p>
</ul>
The transform module also be used to intercept and insert intermediate
processing steps when <b>response.writeStatic()</b>,
<b>response.writeExpr()</b> and <b>response.write()</b> are called to emit
static html, expressions and dynamic content, respectively. It can be useful,
for example, to automatically ensure that expressions never produce output
that is HTML-unsafe, in other words strings that contain characters such as
&amp;, &lt; and &gt;. Many interesting processing
functions can be defined. By default, the transform module leaves all output
untouched. These processing functions, called filters, can be inserted via the
following module functions: <p>
<ul>
<li><b>static</b>( [ fn ] ): <br> Defines the processing performed on all
static HTML strings from this point forwards. The <b>fn</b> parameter is
explained below.</li><p>
<li><b>expr</b>( [ fn ] ): <br> Defines the processing performed on all the
results of all expression tags from this point forwards. The <b>fn</b>
parameter is explained below.</li><p>
<li><b>dynamic</b>( [ fn ] ): <br> Defines the processing performed on all
dynamic content generated, i.e. content generated using response.write in the
code tags. The <b>fn</b> parameter is explained below. </li><p>
</ul>
<p>
Each of the functions above take a single, optional parameter, which specifies
the processing to be performed. The parameter can be one of the following
types:
<ul>
<li><b>None</b>: <br> If the paramter is None, or omitted, then no processing
is performed other converting the output to a string. </li><p>
<li><b>Function</b>: <br> If a parameter of function type is specified, then
that function is called to process the output. The function input can be any
Python type, and the function output may be any Python type. The result is
then converted into a string and emitted. The first parameter to a filter
will always be the object to be processed for output. However, the function
should be properly defined so as to possibly accept other parameters. The
details of how to define filters are explained below. </li><p>
<li><b>String</b>: <br> If a paramter of string type is specified, then the
string should be of the following format: <font
face=courier>"file:name"</font>, where <b>file</b> is the location where
the function is defined and <b>name</b> is the name of the filter. The file
component is optional, and is searched for using the standard module-finding
rules. If only the function name is specified, then the default location
(inside the transform module itself) is used, where the standard Spyce
filters reside. The standard Spyce filters are described below. </li><p>
<li><b>List</b> / <b>Tuple</b>: <br> If a parameter of list or tuple type is
specified, its elements should be functions, strings, lists or
tuples. The compound filter is recursively defined as
<font face=courier>f=fn(...f2(f1())...)</font>, for the parameter
<font face=courier>(f1,f2,...,fn)</font>.
</li><p>
</ul>
<p>
Having explained how to install filters, we now list the standard Spyce
filters and show how they are used:
<ul>
<li><b>ignore_none</b>( o ): <br> Emits any input <b>o</b> except for None,
which is converted into an empty string. </li><p>
<li><b>truncate</b>( o, [maxlen] ): <br> If <b>maxlen</b> is specified,
then only the first maxlen characters of input <b>o</b> are returned,
otherwise the entire original. </li><p>
<li><b>html_encode</b>( o, [also] ): <br> Converts any '&amp;', '&lt;' and
'&gt;' characters of input <b>o</b> into HTML entities for safe inclusion in
among HTML. The optional <b>also</b> parameter can specify, additional
characters that should be entity encoded.</li><p>
<li><b>url_encode</b>( o ): <br> Converts input <b>o</b> into a URL-encoded
string. </li><p>
<li><b>nb_space</b>( o ): <br> Replaces all spaces in input <b>o</b> with
"&amp;nbsp;". </li><p>
<li><b>silence</b>( o ): <br> Outputs nothing. </li><p>
</ul>
<p>
The optional parameters to some of these filters can be passed to the various
write functions as <b>named parameters</b>. They can also be specified in an
expression tag, as in the following example. (One should simply imagine that
the entire expression tag is replaced with a call to response.writeExpr).
<table align=center border=0><tr><td><font face=courier>

<b><pre>[[.import name=transform]]
[[ transform.expr(("truncate", "html_encode")) ]]
[[='This is an unsafe (&lt; &gt; &amp;) string... '*100, <font color=#ff0000>maxlen=500</font>]] </pre></b>
</font></td></tr></table>
<p>
In the example above, the unsafe string is repeated 100 times. It is then
passed through a <font face=courier>truncate</font> filter that will accept
only the first 500 characters. It is then passed through the <font
face=courier>html_encode</font> filter that will convert the unsafe
characters into their safe, equivalent HTML entities. The resulting string is
emitted.<p>
The parameters (specified by their names) are simply accepted by the
appropriate write method (writeExpr() in the case above) and passed along to
the installed filter. Note that in the case of compound filters, the
parameters are passed to <b>ALL</b> the functions. The html_encode filter is
written to ignore the maxlen parameter, and does not fail. <p>
For those who would like to write their own filters, looking at the definition
of the truncate filter will help. The other standard filters are in <font
face="courier">modules/transform.py</font>.
<table align=center border=0><tr><td><font face=courier>

<b><pre>def truncate(o, maxlen=None, **kwargs):</pre></b>
</font></td></tr></table>
<p>
When writing a filter, any function will do, but it is strongly advised to
follow the model above. The important points are:
<ul>
<li>The input o can be of <b>any type</b>, not only a string.</li>
<li>The function <b>result</b> does not have to be string either. It is
automatically stringified at the end.</li>
<li>The function can accept <b>parameters</b> that modify its behaviour, such
as maxlen, above.</li>
<li>It is recommended to provide convenient user <b>defaults</b> for all
parameters.</li>
<li>The last parameter should be <b>**kwargs</b> so that unneeded parameters
are quietly passed along.</li>
</ul>
<p>
Lastly, one can retrieve filters. This can be useful when creating new
functions that depend on existing filters, but can not be compounded using the
tuple syntax above. For example, one might use one filter or another
conditionally. For whatever purpose, the following module function is provided
to retreive standard Spyce filters, if needed: <p>
<ul>
<li><b>create</b>( [ fn ] ): <br> Returns a filter. The <b>fn</b> parameter
can be of type None, function, string, list or tuple and is handled as in
the installation functions discussed above. </li><p>
</ul>
The transform module is flexible, but not complicated to use. The example
below is <i>not</i> examplary of typical use. Rather it highlights some of the
flexibility, so that users can think about creative uses.<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/transform.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">[[.import name=transform]]</font>
<font color="#0000CC">[[\
def tag(o, tags=[], **kwargs):
  import string
  pre = string.join(map(lambda x: '&lt;'+x+'&gt;',tags))
  tags.reverse()
  post = string.join(map(lambda x: '&lt;/'+x+'&gt;',tags))
  return pre+str(o)+post
def bold(o, _tag=tag, **kwargs):
  kwargs['tags'] = ['b']
  return apply(_tag, (o,), kwargs)
def bolditalic(o, _tag=tag, **kwargs):
  kwargs['tags'] = ['b','i']
  return apply(_tag, (o,), kwargs)
myfilter = transform.create(['html_encode', bolditalic])
mystring = 'bold and italic unsafe string: &lt; &gt; &amp;'
def simpletable(o, **kwargs):
  s = '&lt;table border=1&gt;'
  for row in o:
    s=s+'&lt;tr&gt;'
    for cell in row:
      s=s+'&lt;td&gt;'+str(cell)+'&lt;/td&gt;'
    s=s+'&lt;/tr&gt;'
  s = s+'&lt;/table&gt;'
  return s
]]</font>
&lt;html&gt;&lt;body&gt;
  install an expression filter:&lt;br&gt;
  <font color="#0000CC">[[transform.expr(['html_encode', tag])]]</font>
  1.<font color="#CC0000">[[=mystring, tags=['b','i'] ]]</font>
  &lt;br&gt;
  <font color="#0000CC">[[transform.expr(myfilter)]]</font>
  2.<font color="#CC0000">[[=mystring]]</font>
  <font color="#0000CC">[[transform.expr()]]</font>
  &lt;p&gt;
  or use a filter directly:&lt;br&gt;
  1.<font color="#CC0000">[[=transform.create(['html_encode',tag])(mystring,tags=['b','i'])]]</font>
  &lt;br&gt;
  2.<font color="#CC0000">[[=myfilter(mystring)]]</font>
  &lt;p&gt;
  Formatting data in a table...&lt;br&gt;
  <font color="#CC0000">[[=simpletable([ [1,2,3], [4,5,6] ])]]</font>
  &lt;p&gt;
  Though the transform module is flexible, &lt;br&gt;
  most users will probably only install the &lt;br&gt;
  &lt;b&gt;html_encode&lt;/b&gt; filter.
&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/transform.spy">Run this code</a></b>
    </font>
</td></tr></table>
 <p>
<big><a name="mod_compress"></a><b>3.8.9. <font color=#ee0000><i>Compress</i></font></b></big><p>


The compress module supports dynamic compression of Spyce output, and can save
bandwidth in addition to static <a
href="#lang_directive">compaction</a>. The different forms
of compression supported are described below.
<ul>
<li><b>spaces</b>( [ boolean ] ): <br> Controls dynamic space compression.
Dynamic space compression will eliminate consecutive whitespaces (spaces,
newlines and tabs) in the output stream, each time it is flushed. The optional
<b>boolean</b> parameter defaults to true. <p>
<li><b>gzip</b>( [ level ] ): <br> Applies gzip compression to the Spyce
output stream, but only if the browser can support gzip content encoding. Note
that this function will fail if the output stream has already been flushed,
and should generally only be used with buffered output streams. The optional
<b>level</b> parameter specifies the compression level, between 1 and 9
inclusive. A value of zero disables compression. If level is omitted, the
default gzip compression level is used. This function will automatically check
the request's <i>Accept-Encoding</i> header, and set the response's
<i>Content-Encoding</i> header. <p>
</ul>
The example below shows the compression module in use.<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/compress.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">[[.import name=compress args=&quot;gzip=1, spaces=1&quot;]]</font>
<font color="#0000CC">[[\
  response.write('&lt;html&gt;&lt;body&gt;')
  response.write('  Space compression will remove these     spaces.&lt;br&gt;')
  response.write('  gzip compression will highly compress this:&lt;br&gt;')
  for i in range(1000):
    response.write('  hello')
  response.write('&lt;/body&gt;&lt;/html&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/compress.spy">Run this code</a></b>
    </font>
</td></tr></table>
<p>
Note that the compression functions need not be called at the beginning of the
input, but before the output stream is flushed. Also, to really see what is
going on, you should telnet to your web server, and provide something like the
following request.

<table border=0 align=center cellspacing=0 cellpadding=0><tr><td>
<font face=courier>
<b><pre>GET /spyce/examples/compress.spy HTTP/1.1
Accept-Encoding: gzip</pre></b>
</font>
</td></tr></table>
 <p>
<big><a name="mod_include"></a><b>3.8.10. <font color=#ee0000><i>Include</i></font></b></big><p>


Many websites carry a theme across their various pages, which is often
achieved by including a common header or footer. This is best done with a
parent template from the <a href=doc-tag_core.html#parent>spy:parent tag</a>,
but you can also do this with the include module for backwards compatibility
with Spyce 1.x.
<p>
Another option to consider for repeating a common task is
a custom
<a href="#tag_new2">active tag</a>.
<p>
The include module can also pretty print Spyce code or include the contents of
anything in your filesystem.
<ul>
<li><b>spyce</b>( file, [context] ): <br> Dynamically includes the specified
<b>file</b> (corresponding to the Spyce document root, not filesystem),
and processes it as Spyce code. The return value is that of the
included Spyce file. One can optionally provide a <b>context</b> value to
the included file. If omitted, the value defaults to None. All currently
imported modules are passed along into the included file without
re-initialization. However, for each explicit <font
face=courier>[[.import&nbsp;]]</font> tag in the included file, a new
module is initialized and also finalized up at the end of processing. The
include module provides three fields for use inside included files: <p>
<ul>
<li>include.<b>context</b>: This field stores the value passed in at the
point of inclusion. Note that if the value is one that is passed by
reference (as is the case with object, list, and dictionary types), then
the context may be used to pass information back to the including file, in
addition to the return value. </li> <p>
<li>include.<b>vars</b>: If the include context is of type dictionary,
then the vars field is initialized, otherwise it is None. The vars field
provides attribute-based access to the context dictionary, merely for
convenience. In other words, <font face=courier>include.vars.x</font> is
equivalent to <font face=courier>include.context['x']</font>. </li> <p>
</ul>
Note that either the locals() or globals() dictionaries may be passed in as
include contexts. However, be advised that due to Python optimizations of
local variable access, any updates to the locals() dictionary may not be
reflected in the local namespace under all circumstances and all versions of
Python. In fact, this is the reason why the context has been made explicit,
and does not simply grab the locals() dictionary. It may, however, safely be
used for read access. With respect to the globals() dictionary, it is not
advised to <a href="#runtime_transform">pollute</a> this
namespace. </li><p>
<li><b>spyceStr</b>( file, [context] ): <br> Same as <b>spyce</b>(), but
performs no output and instead returns the processed included Spyce file as
a string.</li><p>
<li><b>dump</b>( file, [binary] ): <br> Contents of the <b>file</b>
(from the filesystem -- use spyceUtil.url2file(url, request.filename)
if you need to turn a url into a filesystem path)
are returned. If the <b>binary</b> parameter is true, the file is opened in
binary mode. By default, text mode is used.
<p><b>Be careful</b> not to blindly trust the user to specify which file
to dump, since anything your Spyce process has access to in the filesystem
is fair game.
</li><p>
<li><b>spycecode</b>( file ): <br> Contents of the <b>file</b>
(relative to the Spyce document root)
are returned
as HTML formatted Spyce code. </li><p>
</ul>
The example below (taken from this documentation file), uses a common header
template only requiring two context variables to change the title and the
highlighted link:<br>

<table align=center border=0><tr><td>
<font face=courier>
<b><pre>  [[.import name=include]]
  [[include.spyce('inc/head.spi', 
      {'pagename': 'Documentation', 
       'page': 'manual.html'}) ]]</pre></b>
</font>
</td></tr></table><p>

In <b>head.spi</b>, we use this information to set the title:<p>

<table align=center border=0><tr><td>
<font face=courier>
<b><pre>
  [[.import name=include]]
  &lt;title&gt;[[=include.context['pagename'] ]]&lt;/title&gt;
</pre></b>
</font>
</td></tr></table><p>

By convention, included files are given the extension <b>.spi</b>.<p>