Writing Adapters

Depending on how "simple" the adapter code is allowed to be for a given server environment (see the table for a summary), you will either need to write a small piece of code which initialises and deploys your application, or to produce a more complicated piece of code which satisfies some more demanding server requirements.

Simple Adapters - Using the deploy Function

When deploying an application, it is possible to use a one-shot deployment function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python, Twisted and WSGI configurations. The deploy function is called as follows:

deploy(resource)
deploy(resource, authenticator) # where authenticators are used

For some frameworks, an address may be specified:

deploy(resource, address=(host_string, port_integer))
deploy(resource, authenticator, address=(host_string, port_integer))

And for some frameworks, the return value of the function is important:

something = deploy(resource)
something, something_else = deploy(resource, authenticator)

Here is a summary of which frameworks require address information and which produce important return values from the deploy function:

Framework Address InformationReturn Values
BaseHTTPRequestHandler Supported
CGI Ignored
DjangoIgnoredHandler function
Java ServletIgnoredServlet class
mod_pythonIgnoredHandler function and authenticator function (a 2-tuple)
Twisted Supported (host_string is ignored)
Webware (> 0.8.1)IgnoredURL context object
WSGI Ignored

Debugging Applications

Sometimes, when resources throw unhandled exceptions when processing requests, it is desirable to see the details of the exceptions either in the Web browser or in the console from which the application was started. For such purposes, a parameter to the deploy function can be used:

deploy(resource, handle_errors=0)

The handle_errors parameter, if specified with a false value, will not supress unhandled exceptions with an "internal server error" response, but will instead provide the underlying server environment's report of such exceptions.

Complicated Adapters - Providing Framework-Specific Objects

The remaining frameworks (Java Servlet, mod_python, Webware and Zope) do not support the deploy function due to the way applications are typically integrated into the various server mechanisms. In these cases, it may be worth investigating the examples provided and using their adapter code as a template for the code for your own applications. Here is a summary which indicates the server environments or frameworks which need most work:

Framework Adapter Code Requirements Deployment Process
BaseHTTPRequestHandler Simple - see above Run the adapter code directly
CGI Simple - see above Web server runs the adapter code
DjangoSimple - see aboveThe adapter prepares the handler function
Java Servlet Simple - see above The adapter prepares the servlet class
mod_python Simple - see above The adapter prepares the handler function
Twisted Simple - see above Run the adapter code directly
Webware <= 0.8.1: Must implement InstallInWebKit function
> 0.8.1: Simple - see above
Application must be deployed within WebKit
WSGI Simple - see above Web server runs the adapter code
Zope Must provide lots of Zope administative classes and functions Application must be deployed within Zope

See "Deploying an Application" for more details of the deployment process for each environment.