5.4 System Events

Draco provides functionality to install user defined functions that are called when specific events occur in the system. This can be useful for example to initialize user variables before a request is being processed, or when a session is created.

Defining your own event handler for some system event is very similar to defining a handler for a template. You must subclass Draco's Event class (found in draco.event) and put it in a file named __events__.py in the document root of your web site. Methods in this subclass correspond to system events with the same name.

The next example illustrates how to define an event handler for the sessionStart() system event:

from draco.event import Event

class MyEvent(Event}:

    def sessionStart(self):
	pass

The available events are

applicationStart( )
This event is raised when the application starts up, just before the first request is processed.

applicationEnd( )
This event is raised when the application exists, just before the web server terminates.

childStart( )
This event is raised when a new web server child has started up.

childEnd( )
This event is raised just before a web server child exits.

sessionStart( )
This event is raised when a new session has just been created.

sessionEnd( )
This event is raised when a session expires.
Note: This event is currently not raised. It remains to be seen if this event is useful.

requestStart( )
This event is raised just before a request is handled, i.e. just before the handler is being called.

requestEnd( )
This event is raised when a request has ended.

configChanged( )
This event is raised when a change in the Draco configuration file has been detected. It called after the configuration has been reloaded.

The start events and also the requestEnd() event are always raised in the context of a http request. For example, the applicationStart() is raised not when the web server starts up but rather when it handles its first request. If no requests are made, no of these events are ever raised.

If multiple events must be raised at the same time, they are always raised in their "logical" order. For start events, this is first applicationStart(), then childStart, sessionStart() and finally requestStart(). For end events this order is exactly opposite. The configChanged() event is raised before the sessionStart() event.

Because the start events and requestEnd() are raised synchronously during a http request, all global draco objects are available to their event handlers. On the other hand, the events sessionEnd(), childEnd() and applicationEnd() are raised asynchronously with respect to http requests so the request-related objects request, response, session, user and cookies are not available in their event handlers.

At every request, Draco checks if the file __events__.py has been changed. If it has, Draco automatically reloads the event handlers. This means however that for the asynchronous events the event handler can be out of date if it was changed since the last http request.