4.2 Overview of a Request Handler

A handler is a function that processes a particular phase of a request. Apache processes requests in phases - read the request, process headers, provide content, etc. For every phase, it will call handlers, provided by either the Apache core or one of its modules, such as mod_python which passes control to functions provided by the user and written in Python. A handler written in Python is not any different from a handler written in C, and follows these rules:

A handler function will always be passed a reference to a request object. (Throughout this manual, the request object is often referred to by the req variable.)

Every handler can return:

As an alternative to returning an HTTP error code, handlers can signal an error by raising the apache.SERVER_RETURN exception, and providing an HTTP error code as the exception value, e.g.

raise apache.SERVER_RETURN, apache.HTTP_FORBIDDEN

Handlers can send content to the client using the req.write() method.

Client data, such as POST requests, can be read by using the req.read() function.

Note: The directory of the Apache Python*Handler directive in effect is prepended to the sys.path. If the directive was specified in a server config file outside any <Directory>, then the directory is unknown and not prepended.

An example of a minimalistic handler might be:

from mod_python import apache

def requesthandler(req):
    req.content_type = "text/plain"
    req.write("Hello World!")
    return apache.OK