4.2 Overview of a Handler
Keywords: modpython

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

- `apache.OK`, meaning this phase of the request was handled by this handler and no errors occurred.

- `apache.DECLINED`, meaning this handler refused to handle this phase of the requestand Apache needs to look for another handler.

- `apache.HTTP_ERROR`, meaning an HTTP error occurred. HTTP_ERROR can be:

        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 `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