5.1 pse -- The top level module

The pse module is a package that contains some useful functions and variables that are necessary for PSE servlets to run. Additionally, it contains the plugins package that contains all the plugin modules, and the tags module that contains any custom tag classes.

cache
The cache variable controls output caching of the results of the servlet. The value of cache is a float that represents a timestamp of the same format returned by time.time(). When set to a time in the future, the output of the servlet will be cached until that time. Until then, the servlet will not be run again and only the cached output will be sent.

Cached output is stored in the directory specified by the OutputCacheDir parameter in pse.conf. By default, this is fileTMPDIR/pse_cache (where TMPDIR is your system's default temporary file location).

Note: In order for caching to work, the web server process must have write access to the OutputCacheDir directory specified in the pse.conf file. PSE will attempt to create this directory if it does not exist.

call( filename, [name = value, ...])
The call function can be used to execute an external servlet in a copy of the namespace of the currently running servlet. This has a similar effect of a nested scope, except that variable assignments will not affect the calling servlet's namespace. Any optional keyword arguments are variables to be added to the called servlet's namespace in addition to the caller's.

Any output produced by the external servlet is returned by the call function, so the proper syntax should be:

    <?=pse.call('filename.pt', name1 = value1, name2 = value2) ?>
The file is searched for on the path provided by the IncludePath parameter in the pse.conf file. Any path information provided in the filename parameter will be ignored.

New in version 3.0.

copyright
A string containing the copyright information for PSE.

flush( )
The first call to flush will send whatever HTTP headers have been set and flush output to the client connection. Subsequent calls will flush client output, but any operations that alter the HTTP headers will raise an exception.

New in version 3.0.

form
This is the same as pse.plugins.request.form.

Deprecated since release 3.0. You should reference pse.plugins.request.form instead of pse.form in your code, since form will no longer appear in the pse module in future versions of PSE. See section 5.2.3 for more information.

include( filename)
The include function can be used to execute an external servlet in the same namespace as the currently running servlet. Variable assignments will appear in the caller's namespace when the included servlet has finished executing. This call will be "nested" properly if used inside a servlet executed with pse.call.

Any output produced by the external servlet is returned by the include function, so the proper syntax should be:

    <?=pse.include('filename.pt') ?>
The file is searched for on the path provided by the IncludePath parameter in the pse.conf file. Any path information provided in the filename parameter will be ignored.

New in version 1.2.

Changed in version 2.0.

plugins
The pse.plugins package contains all the plugin modules that were loaded with PSE. See "Plugin Modules" below.

New in version 2.0.

setencoding( [encoding])
The setencoding function can be used to change the default unicode encoding set by the DefaultEncoding parameter in the pse.conf file for the currently running servlet. The encoding is specified using a valid encoding string. If encoding is omitted, the encoding will revert to the DefaultEncoding specified in the pse.conf file.

New in version 3.0.

str( value)
The str function works just like Python's builtin str function/class, except that unicode strings are encoded using the DefaultEncoding specified in the pse.conf file (or changed by calling pse.setencoding). In compiled servlets, expressions used in the <?=expression ?> construct gets passed through pse.str before being sent to the client as output via a pse.write call.

When explicitly producing output to the client, whether through pse.write or via sys.stdout or print, you should use the pse.str function to normalize client output. This is good practice in any case, since pse.str may do more work for you in future versions of PSE.

New in version 3.0.

tags
The pse.tags module is a module that contains all the custom tag classes defined in the module specified by the TagHooksModule option in the pse.conf file. Normally all custom tag classes are available in the global namespace of the servlet, however if you want to be able to access the classes in modules that you import, they can be referenced here.

Any external modules that want to access the custom tags must import this module, using one of the following examples or something similar:

import pse.tags
from pse import tags
from pse.tags import *

The form used will determine how the local namespace is affected by the import. The last form shown above is normally used, since the pse.tags module contains only the custom tag classes that were defined by the progammer.

user_options
A dictionary of options set by the user in the pse.conf file under the section UserOptions. You can pass customized configuration information from the pse.conf file to the running servlet by assigning a value to an arbitrary configuration option under the UserOptions section. These options/values will be converted to a key/value pair in the user_options dictionary. Note that any option name will be converted to all lower case, regardless of the format in the configuration file. All values will be returned as strings.

version
A string containing the number of the currently running version of PSE.

write( output)
The write function is used internally by PSE to send output to the client. In compiled servlets, all template information is translated into a series of pse.write calls. This function should be used in servlets when you want to send output to the client, in lieu of using sys.stdout or print.

While those methods can be used to send output (most Python library modules use them), it will always be safer for your servlet to call pse.write instead, since pse.write may do more work for you in future versions of PSE

New in version 3.0.