#
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