docs: how to upgrade plugins for 1.2

Hi all

Here's a short guide how to upgrade plugins to work with the v1.2 API.

cheers
Steven


With the new Pyblosxom 1.2 release there have been a few API changes.
The idea behind these changes is to make it possible to run Pyblosxom in
environments other then cgi, for example mod_python or twisted. Using
the Pyblosxom wsgi application it should be possible to run Pyblosxom on
any wsgi compliant application server.

Pyblosxom now offers an abstraction layer to access the underlying
environment. That is, things like os.environ, sys.stdin and sys.stdout.
It's importend that you don't access these directly from your plugins as
with some application servers they are not available or are not used in
the same way as with CGI.


Here's a guide how to upgrade your plugins.

os.environ:
Pyblosxom allows access to the os.environ dict through its _http dict.
So instead of using os.environ directly you should use:
http = request.getHttp()
path_info = http['HTTP_PATHINFO']


sys.stdin:
The Pyblosxom Request object implements the following methods to access
the input stream:
__iter__, next, read, readline, readlines, seek, tell

Usage:
data = request.read()
data_part = request.read(1024)
one_line = request.readline()
lines = request.readlines()


sys.stdout:
The output stream should be accessed through the Pyblosxom Response
object. The following methods are implemented:
__iter__, close, flush, next, read, readline, readlines, seek,
tell, write, writelines, setStatus, addHeader

Usage:
response = request.getResponse()
response.addHeader('Status', '200 Ok')
response.addHeader('Content-type', 'text/html')
response.write("Hello World")
response.writelines(["list", "of", "data"])

The status is stored as response.status, the headers as response.headers.


form:
Instead of using:
form = request.getHttp()['form']
use:
form = request.getForm()

Although this is implemented in a backwards compatible way, so both
methods will work.
This allows the form to be created/parsed on demand. So if nobody
actually uses the form, cgi.FieldStorage will not be called. This
prevents the input stream from beeing unnecessarily consumed.


config.py:
You should not access the config dict by directly importing and using
config.py. Instead get it from the request object like:
config = request.getConfiguration()

This is not strictly necessary but it makes things easier as the
configuration is accessed in a known/consistent way. It gives Pyblosxom
the chance to change the config on the fly which can be helpfull for
development and debugging.




-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click