4.9 `psp` - Python Server Pages

The psp 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.

The parser used by psp is written in C (generated using flex) and is therefore very fast.

See 6.2 ``PSP Handler'' for additional PSP information.

Inside the document, Python code needs to be surrounded by "<%" and "%>". Python expressions are enclosed in "<%=" and "%>". A directive can be enclosed in "<%@" and "%>". A comment (which will never be part of the resulting code) can be enclosed in "<%--" and "--%>"

Here is a primitive PSP page that demonstrated use of both code and expression embedded in an HTML document:

  <html>
  <%
  import time
  %>
  Hello world, the time is: <%=time.strftime("%Y-%m-%d, %H:%M:%S")%>
  </html>

Internally, the PSP parser would translate the above page into the following Python code:

  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>
  """)

This code, when executed inside a handler would result in a page displaying words "Hello world, the time is: " followed by current time.

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.

Here is an example:

  <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>

The above will be internally translated to the following Python code:

  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>
  """)

The parser is also smart enough to figure out the indent if the last line of Python ends with ":" (colon). Considering this, and that the indent is reset when a newline is encountered inside "<% %>", the above page can be written as:

  <html>
  <%
  for n in range(3):
  %>
  <p>This paragraph will be 
  repeated 3 times.</p>
  <%
  %>
  This line will only be shown once.<br>
  </html>

However, the above code can be confusing, thus having descriptive comments denoting blocks is highly recommended as a good practice.

The only directive supported at this time is include, here is how it can be used:

<%@ include file="/file/to/include"%>

If the parse() function was called with the dir argument, then the file can be specified as a relative path, otherwise it has to be absolute.

class PSP( req, [, filename, string, vars])

This class represents a PSP object.

req is a request object; filename and string are optional keyword arguments which indicate the source of the PSP code. Only one of these can be specified. If neither is specified, req.filename is used as filename.

vars is a dictionary of global variables. Vars passed in the run() method will override vars passed in here.

This class is used internally by the PSP handler, but can also be used as a general purpose templating tool.

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.

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 anydbm 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 PSPDbmCache Python option, e.g.:

PythonOption PSPDbmCache ``/tmp/pspcache.dbm''

Note that the dbm cache file is not deleted when the server restarts.

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.

run( [vars])

This method will execute the code (produced at object initialization time by parsing and compiling the PSP source). Optional argument vars is a dictionary keyed by strings that will be passed in as global variables.

Additionally, the PSP code will be given global variables req, psp, session and form. A session will be created and assigned to session variable only if session is referenced in the code (the PSP handler examines co_names of the code object to make that determination). Remember that a mere mention of session will generate cookies and turn on session locking, which may or may not be what you want. Similarly, a mod_python FieldStorage object will be instantiated if form is referenced in the code.

The object passed in psp is an instance of PSPInstance.

display_code( ): 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.

Here is an example of how PSP can be used as a templating mechanism:

The template file:

<html>
  <!-- This is a simple psp template called template.html -->
  <h1>Hello, <%=what%>!</h1>
</html>

The handler code:

from mod_python import apache, psp

def handler(req):
    template = psp.PSP(req, filename='template.html')
    template.run({'what':'world'})
    return apache.OK

class PSPInstance( )

An object of this class is passed as a global variable psp to the PSP code. Objects of this class are instantiated internally and the interface to __init__ is purposely undocumented.

set_error_page( filename): 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, exception, which is a 3-tuple returned by sys.exc_info().

apply_data( object[, **kw]): This method will call the callable object object, passing form data as keyword arguments, and return the result.

redirect( location[, permanent=0])

This method will redirect the browser to location location. If permanent is true, then MOVED_PERMANENTLY will be sent (as opposed to MOVED_TEMPORARILY).

Note: 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 IOError exception will be raised.

Example:

<%

# note that the '<' above is the first byte of the page!
psp.redirect('http://www.modpython.org')
%>

Additionally, the psp module provides the following low level functions:

parse( filename[, dir])

This function will open file named filename, read and parse its content and return a string of resulting Python code.

If dir is specified, then the ultimate filename to be parsed is constructed by concatenating dir and filename, and the argument to include directive can be specified as a relative path. (Note that this is a simple concatenation, no path separator will be inserted if dir does not end with one).

parsestring( string)

This function will parse contents of string and return a string of resulting Python code.

4.9 psp - Python Server Pages

4.9 `psp` - Python Server Pages