4.2 Overview of a 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 b the user and written in Python. A handler written in Python is not any different than 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 Request.write() method. Before sending the body of the response, headers must be sent using the Request.send_http_header() method.

Client data, such as POST requests, can be read by using the Request.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.send_http_header()
    req.write("Hello World!")
    return apache.OK