4.2 Overview of a Request Handler
Description: Overview of a Request Handler
Keywords: modpython

#
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