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:
apache.OK, meaning this phase of the request was handled by this
handler and no errors occurred.
apache.DECLINED, meaning this handler has not handled this
phase of the request to completion and Apache needs to look for
another handler in subsequent modules.
apache.HTTP_ERROR, meaning an HTTP error occurred.
HTTP_ERROR can be any of the following:
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.
