General Upgrading Issues

Whenever updating PSE to a higher version, you should always delete
any and all parsed/compiled servlets.  This includes all .p[ty][co]
files.  The format of these files can change from version to
version, and while old versions may seem to run OK, it's probably
just a fluke.

For example, you may use something like the following command to
delete all these files from a directory tree:

*** WARNING!!! THIS WILL DELETE FILES.  USE AT YOUR OWN RISK!!! ***
  $ rm -i `find . -name '*.p[ty][co]'`

Pay special attention to changes in the format and options of the
pse.conf file.  Keep a backup of your original pse.conf file,
install the new default version that comes with PSE, and merge
changes from your old pse.conf into the new one.

Upgrading from PSE 2.x to 3.0

PSE 3.0 now requires Python 2.3.1 and higher.  Versions older than
Python 2.3.0 are not supported.

The main change you will see when upgrading from 2.x to 3.0 is the
package name change from pse to pse_handler.  This was done mainly
to avoid import confusion between the pse handler and the internal
pse package used in servlets.

In your apache configuration, change references from "pse.handler"
to "pse_handler" for each mod_python directive that requires it.
Also, PSE no longer uses the PythonAccessHandler directive in the
apache configuration.  All references must be removed.

Additionally, you will have to change any custom tag modules you may
have to import CustomTag from pse_handler.tags instead of pse.tags
(which now exists solely in running servlets to access custom tags).

Athentication hooks are no longer supported.  They were just a thin
wrapper around mod_python's PythonAuthenHandler mechanism, and as
such were clunky and limited as a feature of PSE.  Instead, consider
using the new pse.plugins.reponse.authenticate function, or just
write a simple mod_python handler from your existing authentication
hook module.

PSE output caching is now accomplished in a separate cache directory
that can be configured in pse.conf rather than in the application
directory.  Additionally, output is cached according to the unparsed
URI rather than simply the servlet file name.  These changes were
done to improve security and performance.

Compiling servlets with the psecompile utility now compile to a .pto
file.  This is not to be confused with the old .pto files, which
contained cached output, which has been replaced by the mechanism
explained above.  As such, PSE will no longer attempt to execute
a .pt/.ptc and .py combination if the .pto file exists.  This should
lead to faster startup and execution times for compiled servlets.

The plugin architecture has changed significantly.  User plugins
built to work with PSE 2.x will continue to work, though you will
receive deprecation warnings in the apache error log.  User plugins
now can (and should) be placed in a directory outside the PSE package
directory, configurable in pse.conf.  Please see the manual for
plugin API changes and other details to bring your plugins up to
date, as deprecated features will be discontinued in a subsequent
version of PSE.

The choice of which session module to use is no longer controlled
by manipulating the modules in the PSE plugins directory; it is now
controlled in the pse.conf file using the Type parameter.  The
default value is dbm, which is consistent with the 2.x default.
Please see the manual for details.

The use of tag_hooks in custom tag modules to identify custom tag
classes was deprecated in 2.x and is no longer supported in 3.0.

There are no major changes in the PSE 3.0 programming interface.
Modules and templates written for PSE 2.x should work without any
changes in PSE 3.0.  However, see Changelog.txt for information
on new functions and functionality available in PSE 3.0.

NOTE: PSE is now thread safe and can work with threaded MPM modules
in apache 2.0.  If you want to use mpm_worker or mpm_winnt, you need
to make sure your custom tags and plugins are thread safe, as well as
any third party library modules you want to use with PSE.

Upgrading from PSE 1.2 to 2.0

1. If you use the ? in attribute values in your templates to execute
arbitrary Python statements, such as:

    <html bgcolor="? print 'red'">

this is no longer supported in versions 2.0 and above.  The ? instead
has the meaning of indicating that if the following condition is true,
then use the attribute; if false, do not use the attribute.  Example:

    <option value="spam" selected="? option_selected == 'spam'">

In this case, if the option_selected variable is the string "spam," then
the "selected" attribute will appear in the tag, otherwise there will be
no "selected" option in the tag.

2. Plugins no longer appear directly as sub-modules of the pse module.
Instead, they now appear in the pse.plugins package.  This was done to
make creating plugin names more flexible.  In version 1.1 and below, it
was possible to overwrite the attribute of pse that had the same name as
the plugin.  In 1.2, it was impossible to create plugins with names such
as "form" to avoid conflicting with pse.form.

Now it is possible to have any valid Python module identifier that
doesn't begin with the underscore (_) as a plugin.  You can
automatically convert your servlets with a command line perl script such
as the following:

    $ perl -pi'.orig' -e 's/pse\.(?!cache|copyright|form|tags|user_options|version)(.+)/pse.plugins.$1/g' *.p[ty]

This will alter all .pt and .py files that reference an attribute or
method of a plugin to the new naming convention.  The original file will
be retained with an .orig extension on the filename.  While this will
probably convert all references for most users, some manual inspection
and editing of files may be required.

3. The pse.include() function now returns a string containing the result
of the included servlet rather than directly outputting the result.
This has been done to allow included servlets to interact with Custom
Tags.  To change your existing code to make this work, convert all
instances of:

    <? pse.include('file') ?>

to:

    <?=pse.include('file') ?>

Please read the manual for more information concerning these changes.


Upgrading from PSE 1.1 to 1.2

If you have previously installed and configured PSE 1.1 or earlier,
then you need to make a changes to your apache configuration file.
In your apache configuration file, change the PythonHandler directive
to PythonHandlerModule.

Additionally, it is now impossible to overwrite builtin pse attributes
with plugins.  Specifically, you can no longer create plugins with the
following names: cache, copyright, form, include, tags, user_options
and version.  If you have created a plugin with one of those names,
then you need to rename it or else it will not be loaded.

Copyright (c)2003-2005 by Nicholas Borko.  All Rights Reserved.
This file is part of the Python Servlet Engine (pse).
Read LICENSE.TXT for licensing information.