PSP¶
Summary¶
Python Server Pages (PSP) provides the capability for producing dynamic web pages for use with the Webware Python Servlet engine simply by writing standard HTML. The HTML code is interspersed with special tags that indicate special actions that should be taken when the page is served. The general syntax for PSP has been based on the popular Java Server Pages specification used with the Java Servlet framework.
Since the Webware Servlets are analogous to Java Servlets, PSP provides a scripting language for use with it that includes all of the power of Python. You will find that PSP compares favorably to other server side web scripting languages, such as ASP, PHP and JSP.
Features of PSP include:
Familiar Syntax (ASP, JSP, PHP)
The power of Python as the scripting language
Full access to the Webware Servlet API
Flexible PSP Base Class framework
Ability to add additional methods to the class produced by PSP
Feedback¶
The PSP for Webware project is fully open source. Help in all areas is encouraged and appreciated. Comments should be directed to the Webware Discussion mailing list. This is a relatively low volume list and you are encouraged to join the list if you wish to participate in the development of PSP or Webware, or if you plan on developing an application using the framework.
General Overview¶
The general process for creating PSP files is similar to creating an HTML page. Simply create a standard HTML page, interspersed with the special PSP tags that your needs require. The file should be saved with an extension of .psp
. Place this file in a directory that is served by Webware. When a request comes in for this page, it will be dynamically compiled into a Webware servlet class, and an instance of this class will be instantiated to serve requests for that page.
There are two general types of PSP tags, <%...%>
and <psp:...>
. Each of these tags have special characteristics, described below.
Whether or not you will need to include standard HTML tags in the start of your PSP page, such as <html>
, <head>
etc. depends on the base class you choose for your PSP class. The default setup does not output any of those tags automatically.
Directives¶
Directives are not output into the HTML output, but instead tell the PSP parser to do something special. Directives have at least two elements, the type of directive, and one or more parameters in the form of param="value"
pairs.
Supported Directives include:
Page Directive – <%@ page ... %>
¶
The page directive tells the PSP parser about special requirements of this page, or sets some optional output options for this page. Directives set in page
apply to the elements in the current PSP source file and to any included files.
Supported Page parameters:
imports
– The imports attribute of the page directive tells the PSP parser to import certain Python modules into the PSP class source file.The format of this directive is as follows:
Example:
<%@ page imports="sys,os"%>
The value of the imports parameter may have multiple, comma separated items.
from X import Y
is supported by separating the source package from the object to be imported with a colon (:), like this:Example:
<%@ page imports="os:path" %>
This will import the path object from the os module.
Please note the
=
sign used in this directive. Those who are used to Python might try to skip it.extends
– The extends attribute of the page tells the PSP parser what base class this Servlet should be derived from.The PSP servlet produced by parsing the PSP file will inherit all of the attributes and methods of the base class.
The Servlet will have access to each of those attributes and methods. They will still need to be accessed using the “self” syntax of Python.
Example:
<%@ page extends="MyPSPBaseClass"%>
This is a very powerful feature of PSP and Webware. The developer can code a series of Servlets that have common functionality for a series of pages, and then use PSP and the extends attribute to change only the pieces of that base servlet that are specific to a certain page. In conjunction with the
method
page attribute, described below, and/or the<psp:method ...>
tag, entire sites can be based on a few custom PSP base classes. The default base class isPSPPage.py
, which is inherited from the standard WebwarePage.py
servlet.You can also have your PSP inherit from multiple base classes. To do this, separate the base classes using commas, for example
<%@ page extends="BaseClass1,BaseClass2"%>
. If you use a base class in<%@ page extends="..."%>
that is not specifically imported in a<%@ page imports="..."%>
directive, the base class will be assumed to follow the servlet convention of being in a file of the same name as the base class plus the “.py” extension.method
– Themethod
attribute of thepage
directive tells the PSP parser which method of the base class the HTML of this PSP page should be placed in and override.Example:
<%@ page method="WriteHTML"%>
Standard methods are
WriteHTML
, of the standardHTTPServlet
class, andwriteBody
, of thePage
andPSPPage
classes. The default iswriteBody
. However, depending on the base class you choose for your PSP class, you may want to override some other method.isThreadSafe
– TheisThreadSafe
attribute ofpage
tells the PSP parser whether the class it is producing can be utilized by multiple threads simultaneously. This is analogous to theisThreadSafe
function in Webware servlets.Example:
<%@ page isThreadSafe="yes"%>
Valid values are “yes” and “no”. The default is “no”.
isInstanceSafe
– TheisInstanceSafe
attribute of thepage
directive tells the PSP parser whether one instance of the class being produced may be used multiple times. This is analogous to the isInstanceSafe function of Webware Servlets.Example:
<%@ page isInstanceSafe="yes"%>
Valid values are “yes” and “no”. The default is “yes”.
indentType
– TheindentType
attribute of thepage
directive tells the parser how to handle block indention in the Python sourcefile it creates. TheindentType
attribute sets whether the sourcefile will be indented with tabs or spaces, or braces. Valid values are “tabs”, “spaces” or “braces”. If this is set to “spaces”, seeindentSpaces
for setting the number of spaces to be used (also, see blocks, below). The default is “spaces”.Example:
<%@ page indentType="tabs"%>
This is a bit of a tricky item, because many editors will automatically replace tabs with spaces in their output, without the user realizing it. If you are having trouble with complex blocks, look at that first.
indentSpaces
– Sets the number of spaces to be used for indentation whenindentType
is set to spaces. The default is “4”.Example:
<%@ page indentSpaces="8" %>
gobbleWhitespace
– Thegobblewhitespace
attribute of thepage
directive tells the PSP parser whether it can safely assume that whitespace characters that it finds between two script tags can be safely ignored. This is a special case directive. It applies when there are two script tags of some kind, and there is only whitespace characters between the two tags. If there is only whitespace, the parser will ignore the whitespace. This is necessary for multipart blocks to function correctly. For example, if you are writing an if/else block, you would have your first script block that starts the if, and then you would end that block and start a new script block that contains the else portion. If there is any whitespace between these two script blocks, andgobbleWhitespace
is turned off, then the parser will add a write statement between the two blocks to output the whitespace into the page. The problem is that the write statement will have the indentation level of the start of the if block. So when the else statement starts, it will not be properly associated with the preceding if, and you’ll get an error.If you do need whitespace between two script blocks, use the
code.Example:
<%@ page gobbleWhitspace="No"%>
Valid values are “yes” and “no”. The default is “yes”.
formatter
– Theformatter
attribute of thepage
directive can be used to specify an alternative formatter function for<%= ... %>
expression blocks. The default value isstr
. You might want to use this if certain types need to be formatted in a certain way across an entire page; for example, if you want all integers to be formatted with commas like “1,234,567” you could make that happen by specifying a custom formatter.Example:
<%@ page imports="MyUtils" %> <%@ page formatter="MyUtils.myFormatter" %>
Include Directive – <%@ include ... %>
¶
The include directive tells the parser to insert another file at this point in the page and to parse it for psp content. It is generally no problem to include an html file this way. However, if you do not want your include file to be parsed, you may use the <psp:include ...>
tag described above.
Example:
<%@ include file="myfile.txt"%>
Developers¶
The original author of PSP is Jay Love and the project was later maintained by Jay and Geoff Talvola. The contributions of the entire Webware community have been invaluable in improving this software.
Some architectural aspects of PSP were inspired by the Jakarta Project.