Let's pretend we have the following configuration:
<Directory /mywebdir> AddHandler python-program .py PythonHandler myscript </Directory>
NB: /mywebdir is an absolute physical path.
And let's say that we have a python program (windows users: substitute forward slashes for backslashes) /mywedir/myscript.py that looks like this:
from mod_python import apache def handler(req): req.content_type = "text/plain" req.send_http_header() req.write("Hello World!") return apache.OK
Here is what's going to happen: The
AddHandler directive tells
Apache that any request for any file ending with .py in the
/mywebdir directory or a subdirectory thereof needs to be
processed by mod_python.
When such a request comes in, Apache starts stepping through its request processing phases calling handlers in mod_python. The mod_python handlers check if a directive for that handler was specified in the configuration. (Remember, it acts as a dispatcher.) In our example, no action will be taken by mod_python for all handlers except for the generic handler. When we get to the generic handler, mod_python will notice "PythonHandler myscript" directive and do the following:
PythonHandlerdirective was found to
myscript. (Note that if
myscriptwas in a subdirectory of the directory where
PythonHandlerwas specified, then the import would not work because said subdirectory would not be in the
sys.path. One way around this is to use package notation, e.g. "PythonHandler subdir.myscript".)
from mod_python import apache
This imports the apache module which provides us the interface to Apache. With a few rare exceptions, every mod_python program will have this line.
This is our handler function declaration. It is called
"handler" because mod_python takes the name of the directive,
converts it to lower case and removes the word
"handler". You could name it
something else, and specify it explicitly in the directive using the
special "::" notation. For example, if the handler function was
called "spam", then the directive would be
Note that a handler must take one argument - the mysterious Request object. There is really no mystery about it though. The Request object is an object that provides all of the information about this particular request - such as the IP of client, the headers, the URI, etc. The communication back to the client is also done via the Request object, i.e. there is no "response" object.
req.content_type = "text/plain"
This sets the content type to
"text/plain". The default is usually
"text/html", but since our handler doesn't produce any html,
"text/plain" is more appropriate.
This function sends the HTTP headers to the client. You can't really
start writing to the client without sending the headers first. Note
that one of the headers is
"Content-Type". So if you want to set
custom content-types, you better do it before you call
This writes the
"Hello World!" string to the client. (Did I really
have to explain this one?)
This tells Apache that everything went OK and that the request has been processed. If things did not go OK, that line could be return apache.HTTP_INTERNAL_SERVER_ERROR or return apache.HTTP_FORBIDDEN. When things do not go OK, Apache will log the error and generate an error message for the client.
Some food for thought: If you were paying attention, you noticed that nowhere did it say that in order for all of the above to happen, the URL needs to refer to myscript.py. The only requirement was that it refers to a .py file. In fact the name of the file doesn't matter, and the file referred to in the URL doesn't have to exist. So, given the above configuration, "http://myserver/mywebdir/myscript.py" and "http://myserver/mywebdir/montypython.py" would give the exact same result.
At this point, if you didn't understand the above paragraph, go back and read it again, until you do.