<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <link rel="STYLESHEET" href="modpython.css" type='text/css' /> <link rel="first" href="modpython.html" title='Mod_python Manual' /> <link rel='contents' href='contents.html' title="Contents" /> <link rel='index' href='genindex.html' title='Index' /> <link rel='last' href='about.html' title='About this document...' /> <link rel='help' href='about.html' title='About this document...' /> <link rel="prev" href="pyapi-sess.html" /> <link rel="parent" href="pythonapi.html" /> <link rel="next" href="directives.html" /> <meta name='aesop' content='information' /> <title>4.9 psp - Python Server Pages</title> </head> <body> <DIV CLASS="navigation"> <div id='top-navigation-panel' xml:id='top-navigation-panel'> <table align="center" width="100%" cellpadding="0" cellspacing="2"> <tr> <td class='online-navigation'><a rel="prev" title="4.8.2 Examples" href="pyapi-sess-example.html"><img src='previous.png' border='0' height='32' alt='Previous Page' width='32' /></A></td> <td class='online-navigation'><a rel="parent" title="4. Python API" href="pythonapi.html"><img src='up.png' border='0' height='32' alt='Up One Level' width='32' /></A></td> <td class='online-navigation'><a rel="next" title="5. Apache Configuration Directives" href="directives.html"><img src='next.png' border='0' height='32' alt='Next Page' width='32' /></A></td> <td align="center" width="100%">Mod_python Manual</td> <td class='online-navigation'><a rel="contents" title="Table of Contents" href="contents.html"><img src='contents.png' border='0' height='32' alt='Contents' width='32' /></A></td> <td class='online-navigation'><img src='blank.png' border='0' height='32' alt='' width='32' /></td> <td class='online-navigation'><a rel="index" title="Index" href="genindex.html"><img src='index.png' border='0' height='32' alt='Index' width='32' /></A></td> </tr></table> <div class='online-navigation'> <b class="navlabel">Previous:</b> <a class="sectref" rel="prev" href="pyapi-sess-example.html">4.8.2 Examples</A> <b class="navlabel">Up:</b> <a class="sectref" rel="parent" href="pythonapi.html">4. Python API</A> <b class="navlabel">Next:</b> <a class="sectref" rel="next" href="directives.html">5. Apache Configuration Directives</A> </div> <hr /></div> </DIV> <!--End of Navigation Panel--> <H1><A NAME="SECTION006900000000000000000"></A><A NAME="pyapi-psp"></A> <BR> 4.9 <tt class="module">psp</tt> - Python Server Pages </H1> <A NAME="module-psp"></A> <P> The <tt class="module">psp</tt> module provides a way to convert text documents (including, but not limited to HTML documents) containing Python code embedded in special brackets into pure Python code suitable for execution within a mod_python handler, thereby providing a versatile mechanism for delivering dynamic content in a style similar to ASP, JSP and others. <P> The parser used by <tt class="module">psp</tt> is written in C (generated using flex) and is therefore very fast. <P> <em>See <A href="hand-psp.html#hand-psp">7.2</A> ``PSP Handler'' for additional PSP information.</em> <P> Inside the document, Python <i class="dfn">code</i> needs to be surrounded by "<tt class="samp"><%</tt>" and "<tt class="samp">%></tt>". Python <i class="dfn">expressions</i> are enclosed in "<tt class="samp"><%=</tt>" and "<tt class="samp">%></tt>". A <i class="dfn">directive</i> can be enclosed in "<tt class="samp"><%@</tt>" and "<tt class="samp">%></tt>". A comment (which will never be part of the resulting code) can be enclosed in "<tt class="samp"><%--</tt>" and "<tt class="samp">--%></tt>" <P> Here is a primitive PSP page that demonstrated use of both code and expression embedded in an HTML document: <P> <div class="verbatim"><pre> <html> <% import time %> Hello world, the time is: <%=time.strftime("%Y-%m-%d, %H:%M:%S")%> </html> </pre></div> <P> Internally, the PSP parser would translate the above page into the following Python code: <P> <div class="verbatim"><pre> req.write("""<html> """) import time req.write(""" Hello world, the time is: """); req.write(str(time.strftime("%Y-%m-%d, %H:%M:%S"))); req.write(""" </html> """) </pre></div> <P> This code, when executed inside a handler would result in a page displaying words "<tt class="samp">Hello world, the time is: </tt>" followed by current time. <P> Python code can be used to output parts of the page conditionally or in loops. Blocks are denoted from within Python code by indentation. The last indentation in Python code (even if it is a comment) will persist through the document until either end of document or more Python code. <P> Here is an example: <div class="verbatim"><pre> <html> <% for n in range(3): # This indent will persist %> <p>This paragraph will be repeated 3 times.</p> <% # This line will cause the block to end %> This line will only be shown once.<br> </html> </pre></div> <P> The above will be internally translated to the following Python code: <P> <div class="verbatim"><pre> req.write("""<html> """) for n in range(3): # This indent will persist req.write(""" <p>This paragraph will be repeated 3 times.</p> """) # This line will cause the block to end req.write(""" This line will only be shown once.<br> </html> """) </pre></div> <P> The parser is also smart enough to figure out the indent if the last line of Python ends with "<tt class="samp">:</tt>" (colon). Considering this, and that the indent is reset when a newline is encountered inside "<tt class="samp"><% %></tt>", the above page can be written as: <P> <div class="verbatim"><pre> <html> <% for n in range(3): %> <p>This paragraph will be repeated 3 times.</p> <% %> This line will only be shown once.<br> </html> </pre></div> <P> However, the above code can be confusing, thus having descriptive comments denoting blocks is highly recommended as a good practice. <P> The only directive supported at this time is <code>include</code>, here is how it can be used: <P> <div class="verbatim"><pre> <%@ include file="/file/to/include"%> </pre></div> <P> If the <tt class="function">parse()</tt> function was called with the <var>dir</var> argument, then the file can be specified as a relative path, otherwise it has to be absolute. <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-258' xml:id='l2h-258' class="class">PSP</tt></b>(</nobr></td> <td><var>req, </var><big>[</big><var>, filename, string, vars</var><big>]</big><var></var>)</td></tr></table></dt> <dd> This class represents a PSP object. <P> <var>req</var> is a request object; <var>filename</var> and <var>string</var> are optional keyword arguments which indicate the source of the PSP code. Only one of these can be specified. If neither is specified, <code>req.filename</code> is used as <var>filename</var>. <P> <var>vars</var> is a dictionary of global variables. Vars passed in the <tt class="method">run()</tt> method will override vars passed in here. <P> This class is used internally by the PSP handler, but can also be used as a general purpose templating tool. <P> When a file is used as the source, the code object resulting from the specified file is stored in a memory cache keyed on file name and file modification time. The cache is global to the Python interpreter. Therefore, unless the file modification time changes, the file is parsed and resulting code is compiled only once per interpreter. <P> The cache is limited to 512 pages, which depending on the size of the pages could potentially occupy a significant amount of memory. If memory is of concern, then you can switch to dbm file caching. Our simple tests showed only 20% slower performance using bsd db. You will need to check which implementation <tt class="module">anydbm</tt> defaults to on your system as some dbm libraries impose a limit on the size of the entry making them unsuitable. Dbm caching can be enabled via <code>mod_python.psp.cache_database_filename</code> Python option, e.g.: <P> <div class="verbatim"><pre> PythonOption mod_python.psp.cache_database_filename ``/tmp/pspcache.dbm'' </pre></div> Note that the dbm cache file is not deleted when the server restarts. <P> Unlike with files, the code objects resulting from a string are cached in memory only. There is no option to cache in a dbm file at this time. <P> Note that the above name for the option setting was only changed to this value in mod_python 3.3. If you need to retain backward compatability with older versions of mod_python use the <code>PSPDbmCache</code> option instead. <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><tt id='l2h-259' xml:id='l2h-259' class="method">run</tt></b>(</nobr></td> <td><var></var><big>[</big><var>vars, flush</var><big>]</big><var></var>)</td></tr></table></dt> <dd> This method will execute the code (produced at object initialization time by parsing and compiling the PSP source). Optional argument <var>vars</var> is a dictionary keyed by strings that will be passed in as global variables. Optional argument <var>flush</var> is a boolean flag indicating whether output should be flushed. The default is not to flush output. <P> Additionally, the PSP code will be given global variables <code>req</code>, <code>psp</code>, <code>session</code> and <code>form</code>. A session will be created and assigned to <code>session</code> variable only if <code>session</code> is referenced in the code (the PSP handler examines <code>co_names</code> of the code object to make that determination). Remember that a mere mention of <code>session</code> will generate cookies and turn on session locking, which may or may not be what you want. Similarly, a mod_python <tt class="class">FieldStorage</tt> object will be instantiated if <code>form</code> is referenced in the code. <P> The object passed in <code>psp</code> is an instance of <tt class="class">PSPInterface</tt>. <P> </dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><tt id='l2h-260' xml:id='l2h-260' class="method">display_code</tt></b>(</nobr></td> <td><var></var>)</td></tr></table></dt> <dd> Returns an HTML-formatted string representing a side-by-side listing of the original PSP code and resulting Python code produced by the PSP parser. </dl> <P> Here is an example of how <tt class="class">PSP</tt> can be used as a templating mechanism: <P> The template file: <div class="verbatim"><pre> <html> <!-- This is a simple psp template called template.html --> <h1>Hello, <%=what%>!</h1> </html> </pre></div> The handler code: <div class="verbatim"><pre> from mod_python import apache, psp def handler(req): template = psp.PSP(req, filename='template.html') template.run({'what':'world'}) return apache.OK </pre></div> <P> </dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-261' xml:id='l2h-261' class="class">PSPInterface</tt></b>(</nobr></td> <td><var></var>)</td></tr></table></dt> <dd> An object of this class is passed as a global variable <code>psp</code> to the PSP code. Objects of this class are instantiated internally and the interface to <tt class="method">__init__</tt> is purposely undocumented. <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><tt id='l2h-262' xml:id='l2h-262' class="method">set_error_page</tt></b>(</nobr></td> <td><var>filename</var>)</td></tr></table></dt> <dd> Used to set a psp page to be processed when an exception occurs. If the path is absolute, it will be appended to document root, otherwise the file is assumed to exist in the same directory as the current page. The error page will receive one additional variable, <code>exception</code>, which is a 3-tuple returned by <code>sys.exc_info()</code>. </dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><tt id='l2h-263' xml:id='l2h-263' class="method">apply_data</tt></b>(</nobr></td> <td><var>object</var><big>[</big><var>, **kw</var><big>]</big><var></var>)</td></tr></table></dt> <dd> This method will call the callable object <var>object</var>, passing form data as keyword arguments, and return the result. </dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><tt id='l2h-264' xml:id='l2h-264' class="method">redirect</tt></b>(</nobr></td> <td><var>location</var><big>[</big><var>, permanent=0</var><big>]</big><var></var>)</td></tr></table></dt> <dd> This method will redirect the browser to location <var>location</var>. If <var>permanent</var> is true, then <tt class="constant">MOVED_PERMANENTLY</tt> will be sent (as opposed to <tt class="constant">MOVED_TEMPORARILY</tt>). <P> <div class="note"><b class="label">Note:</b> Redirection can only happen before any data is sent to the client, therefore the Python code block calling this method must be at the very beginning of the page. Otherwise an <tt class="exception">IOError</tt> exception will be raised. </div> <P> Example: <div class="verbatim"><pre> <% # note that the '<' above is the first byte of the page! psp.redirect('http://www.modpython.org') %> </pre></div> </dl> <P> </dl> <P> Additionally, the <tt class="module">psp</tt> module provides the following low level functions: <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><tt id='l2h-265' xml:id='l2h-265' class="function">parse</tt></b>(</nobr></td> <td><var>filename</var><big>[</big><var>, dir</var><big>]</big><var></var>)</td></tr></table></dt> <dd> <P> This function will open file named <var>filename</var>, read and parse its content and return a string of resulting Python code. <P> If <var>dir</var> is specified, then the ultimate filename to be parsed is constructed by concatenating <var>dir</var> and <var>filename</var>, and the argument to <code>include</code> directive can be specified as a relative path. (Note that this is a simple concatenation, no path separator will be inserted if <var>dir</var> does not end with one). </dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> <td><nobr><b><tt id='l2h-266' xml:id='l2h-266' class="function">parsestring</tt></b>(</nobr></td> <td><var>string</var>)</td></tr></table></dt> <dd> <P> This function will parse contents of <var>string</var> and return a string of resulting Python code. <P> </dl> <DIV CLASS="navigation"> <div class='online-navigation'> <p></p><hr /> <table align="center" width="100%" cellpadding="0" cellspacing="2"> <tr> <td class='online-navigation'><a rel="prev" title="4.8.2 Examples" href="pyapi-sess-example.html"><img src='previous.png' border='0' height='32' alt='Previous Page' width='32' /></A></td> <td class='online-navigation'><a rel="parent" title="4. Python API" href="pythonapi.html"><img src='up.png' border='0' height='32' alt='Up One Level' width='32' /></A></td> <td class='online-navigation'><a rel="next" title="5. Apache Configuration Directives" href="directives.html"><img src='next.png' border='0' height='32' alt='Next Page' width='32' /></A></td> <td align="center" width="100%">Mod_python Manual</td> <td class='online-navigation'><a rel="contents" title="Table of Contents" href="contents.html"><img src='contents.png' border='0' height='32' alt='Contents' width='32' /></A></td> <td class='online-navigation'><img src='blank.png' border='0' height='32' alt='' width='32' /></td> <td class='online-navigation'><a rel="index" title="Index" href="genindex.html"><img src='index.png' border='0' height='32' alt='Index' width='32' /></A></td> </tr></table> <div class='online-navigation'> <b class="navlabel">Previous:</b> <a class="sectref" rel="prev" href="pyapi-sess-example.html">4.8.2 Examples</A> <b class="navlabel">Up:</b> <a class="sectref" rel="parent" href="pythonapi.html">4. Python API</A> <b class="navlabel">Next:</b> <a class="sectref" rel="next" href="directives.html">5. Apache Configuration Directives</A> </div> </div> <hr /> <span class="release-info">Release 3.3.1, documentation updated on January 29, 2007.</span> </DIV> <!--End of Navigation Panel--> </BODY> </HTML>