4.2 Handlers

Handlers are Python functions that are responsible for processing the remote clients request and storing the results of this request in the interface namespace. The templates then read this interface and format the results.

There is a one to one correspondence between handlers and templates: exactly one handler function corresponds to exactly one template. We have already seen how to define a handler function for a specific template. You must subclass Draco's Handler class (found in draco.handler) and put it in a file named __handler__.py in the same directory as the template. Methods in this class correspond to templates with the same name plus the default extension. So, for example, the following Python fragment defines a handler function for the template hello.dsp4.1.

from draco.handler import Handler

class MyHandler(Handler):

    def hello(self, path, args):
        pass

The handler function is passed path and args parameters that together describe the request. The path parameter contains a list of path components that were given after the template name. Empty path components are eliminated. This parameter corresponds to CGI's $PATH_INFO parameter.

The args parameter is a namespace describing the GET and POST parameters that were passed with the request. The namespace is indexed by variable name. The values are either Python strings -- in the case of simple parameters -- or a FileUpload instance -- in the case of a file upload parameter. If there were multiple parameters with the same name, a list of strings and FileUpload instances is returned.

The results of the action performed in the handler are communicated to the template via the interface. The interface is a namespace that can contain variables of any Python type including class instances.

Handlers can also be used for authentication purposes. To control access to a certain resource, you can define a method __authenticate__ in your handler class. This function controls access to all templates in the directory.

__authenticate__( template)
Controls access to templates in the directory. If access to the template template is allowed, this should return AUTH_OK. If not, AUTH_DENY should be returned instead. Note that the template argument is the name of the requested template without extension.

Both AUTH_OK and AUTH_DENY are data members of the Handler class:

AUTH_OK
Authentication is granted.

AUTH_DENY
Authentication is denied.

If Draco finds no handler for a requested template, it checks whether a handler function with the name __default__ is defined in the handler class. If it is, it is used as the handler function for the template. This can be used to implement a "catch all" handlers for all requests in a directory.

__default__( path, args)
This method is called when no handler function for a requested template is found. It is passed path and args parameters just like normal handler functions.

If the default handler is not found, Draco performs the same as if the handler were empty. A template can still exist but it will have an empty interface. This can be used for serving static html pages, while still having some of Draco's advantages like session management and image size detection.

Oppositely, it is also possbible to have a handler without an accompanying template. In this case, the handler function itself is responsible for writing the output to the client. This can be done using the response object, see section 5.2.5. A handler without template is useful when for example you want to generate an image on the fly.

The normal way to finish a http request is to return from the handler function. The template (if it exists) will be parsed and written to the client. The HTTP request exits with a code 200 (HTTP_OK).

There are two other ways to exit from a handler. The first way is to raise one of the HttpResponse exceptions, which can be useful in error situations. For more information on these exceptions, see section 5.1. The second way to exit from a handler is to call a nonreturing function. Draco's response object contains two function that do not return: redirect() and exit().



Footnotes

...hello.dsp4.1
Assuming Draco is configured to use the default .dsp extension.