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:

• 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:

  HTTP_CONTINUE                     = 100
  HTTP_SWITCHING_PROTOCOLS          = 101
  HTTP_PROCESSING                   = 102
  HTTP_OK                           = 200
  HTTP_CREATED                      = 201
  HTTP_ACCEPTED                     = 202
  HTTP_NON_AUTHORITATIVE            = 203
  HTTP_NO_CONTENT                   = 204
  HTTP_RESET_CONTENT                = 205
  HTTP_PARTIAL_CONTENT              = 206
  HTTP_MULTI_STATUS                 = 207
  HTTP_MULTIPLE_CHOICES             = 300
  HTTP_MOVED_PERMANENTLY            = 301
  HTTP_MOVED_TEMPORARILY            = 302
  HTTP_SEE_OTHER                    = 303
  HTTP_NOT_MODIFIED                 = 304
  HTTP_USE_PROXY                    = 305
  HTTP_TEMPORARY_REDIRECT           = 307
  HTTP_BAD_REQUEST                  = 400
  HTTP_UNAUTHORIZED                 = 401
  HTTP_PAYMENT_REQUIRED             = 402
  HTTP_FORBIDDEN                    = 403
  HTTP_NOT_FOUND                    = 404
  HTTP_METHOD_NOT_ALLOWED           = 405
  HTTP_NOT_ACCEPTABLE               = 406
  HTTP_PROXY_AUTHENTICATION_REQUIRED= 407
  HTTP_REQUEST_TIME_OUT             = 408
  HTTP_CONFLICT                     = 409
  HTTP_GONE                         = 410
  HTTP_LENGTH_REQUIRED              = 411
  HTTP_PRECONDITION_FAILED          = 412
  HTTP_REQUEST_ENTITY_TOO_LARGE     = 413
  HTTP_REQUEST_URI_TOO_LARGE        = 414
  HTTP_UNSUPPORTED_MEDIA_TYPE       = 415
  HTTP_RANGE_NOT_SATISFIABLE        = 416
  HTTP_EXPECTATION_FAILED           = 417
  HTTP_UNPROCESSABLE_ENTITY         = 422
  HTTP_LOCKED                       = 423
  HTTP_FAILED_DEPENDENCY            = 424
  HTTP_INTERNAL_SERVER_ERROR        = 500
  HTTP_NOT_IMPLEMENTED              = 501
  HTTP_BAD_GATEWAY                  = 502
  HTTP_SERVICE_UNAVAILABLE          = 503
  HTTP_GATEWAY_TIME_OUT             = 504
  HTTP_VERSION_NOT_SUPPORTED        = 505
  HTTP_VARIANT_ALSO_VARIES          = 506
  HTTP_INSUFFICIENT_STORAGE         = 507
  HTTP_NOT_EXTENDED                 = 510
  

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