\chapter{Tutorial\label{tutorial}}

\begin{flushright}

\emph{So how can I make this work?}

\end{flushright}

\emph{This is a quick guide to getting started with mod_python

installation manual!}

\emph{It is also highly recommended to read (at least the top part of)

completing this tutorial.}

\section{A Quick Start with the Publisher Handler\label{tut-pub}}

This section provides a quick overview of the Publisher handler for

those who would like to get started without getting into too much

detail. A more thorough explanation of how mod_python handlers work

and what a handler actually is follows on in the later sections of the

tutorial.

The \code{publisher} handler is provided as one of the standard

mod_python handlers. To get the publisher handler working, you will

need the following lines in your config:

\begin{verbatim}

\end{verbatim}

The following example will demonstrate a simple feedback form. The

form will ask for the name, e-mail address and a comment and construct

an e-mail to the webmaster using the information submitted by the

user. This simple application consists of two files:

\filenq{form.html} - the form to collect the data, and

\filenq{form.py} - the target of the form's action.

Here is the html for the form:

\begin{verbatim}

\end{verbatim}

Note the \code{action} element of the \code{<form>} tag points to

\code{form.py/email}. We are going to create a file called

\filenq{form.py}, like this:

\begin{verbatim}

\end{verbatim}

When the user clicks the Submit button, the publisher handler will

load the \function{email} function in the \module{form} module,

passing it the form fields as keyword arguments. It will also pass the

request object as \code{req}.

Note that you do not have to have \code{req} as one of the arguments

if you do not need it. The publisher handler is smart enough to pass

your function only those arguments that it will accept.

The data is sent back to the browser via the return value of the

function.

Even though the Publisher handler simplifies mod_python programming a

great deal, all the power of mod_python is still available to this

program, since it has access to the request object. You can do all the

same things you can do with a ``native'' mod_python handler, e.g. set

custom headers via \code{req.headers_out}, return errors by raising

\exception{apache.SERVER_ERROR} exceptions, write or read directly to

and from the client via \method{req.write()} and \method{req.read()},

etc.

Read Section \ref{hand-pub} \citetitle[hand-pub.html]{Publisher Handler}

for more information on the publisher handler.

\section{Quick Overview of how Apache Handles Requests\label{tut-overview}}

If you would like delve in deeper into the functionality of

mod_python, you need to understand what a handler is.

Apache processes requests in \dfn{phases}. For example, the first

phase may be to authenticate the user, the next phase to verify

whether that user is allowed to see a particular file, then (next

phase) read the file and send it to the client. A typical static file

request involves three phases: (1) translate the requested URI to a

file location (2) read the file and send it to the client, then (3)

log the request. Exactly which phases are processed and how varies

greatly and depends on the configuration.

A \dfn{handler} is a function that processes one phase. There may be

more than one handler available to process a particular phase, in

which case they are called by Apache in sequence. For each of the

phases, there is a default Apache handler (most of which by default

perform only very basic functions or do nothing), and then there are

additional handlers provided by Apache modules, such as mod_python.

Mod_python provides every possible handler to Apache. Mod_python

handlers by default do not perform any function, unless specifically

told so by a configuration directive. These directives begin with

\samp{Python} and end with \samp{Handler}

(e.g. \code{PythonAuthenHandler}) and associate a phase with a Python

function. So the main function of mod_python is to act as a dispatcher

between Apache handlers and Python functions written by a developer

like you.

The most commonly used handler is \code{PythonHandler}. It handles the

phase of the request during which the actual content is

provided. Because it has no name, it is sometimes referred to as as

\dfn{generic} handler. The default Apache action for this handler is

to read the file and send it to the client. Most applications you will

write will override this one handler. To see all the possible

handlers, refer to Section \ref{directives},

\citetitle[directives.html]{Apache Directives}.

\section{So what Exactly does Mod-python do?\label{tut-what-it-do}}

Let's pretend we have the following configuration:

\begin{verbatim}

\end{verbatim}

\strong{NB:} \filenq{/mywebdir} is an absolute physical path.

And let's say that we have a python program (Windows users: substitute

forward slashes for backslashes) \file{/mywedir/myscript.py} that looks like

this:

\begin{verbatim}

\end{verbatim}

Here is what's going to happen: The \code{AddHandler} directive tells

Apache that any request for any file ending with \file{.py} in the

\file{/mywebdir} directory or a subdirectory thereof needs to be

processed by mod_python. The \samp{PythonHandler myscript} directive

tells mod_python to process the generic handler using the

\code{myscript} script. The \samp{PythonDebug On} directive instructs

mod_python in case of an Python error to send error output to the

client (in addition to the logs), very useful during development.

When a request comes in, Apache starts stepping through its request

processing phases calling handlers in mod_python. The mod_python

handlers check whether 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 \samp{PythonHandler myscript} directive and do

the following:

\begin{enumerate}

If not already done, prepend the directory in which the

\code{PythonHandler} directive was found to \code{sys.path}.

Attempt to import a module by name \code{myscript}. (Note that if

\code{myscript} was in a subdirectory of the directory where

\code{PythonHandler} was specified, then the import would not work

because said subdirectory would not be in the \code{sys.path}. One

way around this is to use package notation, e.g. \samp{PythonHandler

subdir.myscript}.)

\item

Look for a function called \code{handler} in \code{myscript}.

Call the function, passing it a request object. (More on what a

request object is later)

At this point we're inside the script:

\begin{itemize}

\item

\begin{verbatim}

\end{verbatim}

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.

\item

\begin{verbatim}

\end{verbatim}

\index{handler} This is our \dfn{handler} function declaration. It

is called \samp{handler} because mod_python takes the name of the

directive, converts it to lower case and removes the word

\samp{python}. Thus \samp{PythonHandler} becomes

\samp{handler}. You could name it something else, and specify it

explicitly in the directive using \samp{::}. For example, if the

handler function was called \samp{spam}, then the directive would

be \samp{PythonHandler myscript::spam}.

Note that a handler must take one argument - the request

object. 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.

\item

\begin{verbatim}

\end{verbatim}

This sets the content type to \samp{text/plain}. The default is usually

\samp{text/html}, but since our handler doesn't produce any html,

\samp{text/plain} is more appropriate.

\strong{Important:} you should \strong{always} make sure this is set

\strong{before} any call to \samp{req.write}. When you first call

\samp{req.write}, the response HTTP header is sent to the client and all

subsequent changes to the content type (or other HTTP headers) are simply

lost.

\item

\begin{verbatim}

\end{verbatim}

This writes the \samp{Hello World!} string to the client. (Did I really

have to explain this one?)

\item

\begin{verbatim}

\end{verbatim}

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

\constant{apache.HTTP_INTERNAL_SERVER_ERROR} or return

\constant{apache.HTTP_FORBIDDEN}. When things do not go OK, Apache

will log the error and generate an error message for the client.

\end{itemize}

\end{enumerate}

\strong{Some food for thought:} If you were paying attention, you

noticed that the text above didn't specify that in order for the

handler code to be executed, the URL needs to refer to

\filenq{myscript.py}. The only requirement was that it refers to a

\filenq{.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, \samp{http://myserver/mywebdir/myscript.py} and

\samp{http://myserver/mywebdir/montypython.py} would give the exact

same result. The important thing to understand here is that a handler

augments the server behaviour when processing a specific type of file,

not an individual file.

\emph{At this point, if you didn't understand the above paragraph, go

back and read it again, until you do.}

\section{Now something More Complicated - Authentication\label{tut-more-complicated}}

Now that you know how to write a primitive handler, let's try

something more complicated.

Let's say we want to password-protect this directory. We want the

login to be \samp{spam}, and the password to be \samp{eggs}.

First, we need to tell Apache to call our \emph{authentication}

handler when authentication is needed. We do this by adding the

\code{PythonAuthenHandler}. So now our config looks like this:

\begin{verbatim}

\end{verbatim}

Notice that the same script is specified for two different

handlers. This is fine, because if you remember, mod_python will look

for different functions within that script for the different handlers.

Next, we need to tell Apache that we are using Basic HTTP

authentication, and only valid users are allowed (this is fairly basic

Apache stuff, so we're not going to go into details here). Our config

looks like this now:

\begin{verbatim}

\end{verbatim}

Now we need to write an authentication handler function in

\file{myscript.py}. A basic authentication handler would look like

this:

\begin{verbatim}

\end{verbatim}

Let's look at this line by line:

\begin{itemize}

\begin{verbatim}

\end{verbatim}

This is the handler function declaration. This one is called

\code{authenhandler} because, as we already described above,

mod_python takes the name of the directive

(\code{PythonAuthenHandler}), drops the word \samp{Python} and converts

it lower case.

\begin{verbatim}

\end{verbatim}

This is how we obtain the password. The basic HTTP authentication

transmits the password in base64 encoded form to make it a little

bit less obvious. This function decodes the password and returns it

as a string. Note that we have to call this function before obtaining

the user name.

\begin{verbatim}

\end{verbatim}

This is how you obtain the username that the user entered.

\begin{verbatim}

\end{verbatim}

We compare the values provided by the user, and if they are what we

were expecting, we tell Apache to go ahead and proceed by returning

\constant{apache.OK}. Apache will then consider this phase of the

request complete, and proceed to the next phase. (Which in this case

would be \function{handler()} if it's a \code{.py} file).

\begin{verbatim}

\end{verbatim}

Else, we tell Apache to return \constant{HTTP_UNAUTHORIZED} to the

client, which usually causes the browser to pop a dialog box asking

for username and password.

\end{itemize}

\section{Your Own 404 Handler\label{tut-404-handler}}

In some cases, you may wish to return a 404 (\constant{HTTP_NOT_FOUND}) or

other non-200 result from your handler. There is a trick here. if you

return \constant{HTTP_NOT_FOUND} from your handler, Apache will handle

rendering an error page. This can be problematic if you wish your handler

to render it's own error page.

In this case, you need to set \code{req.status = apache.HTTP_NOT_FOUND},

render your page, and then \code{return(apache.OK)}:

\begin{verbatim}

\end{verbatim}