\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 
programming once you have it installed. This is \textbf{not} an
installation manual!}

\emph{It is also highly recommended to read (at least the top part of)
Section \ref{pythonapi}, \citetitle[pythonapi.html]{Python API} after
completing this tutorial.}

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

It may seem like a little too much for starters, but you need to
understand what a handler is in order to use mod_python. And it's
really rather simple.

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. Most requests consist of two phases:
(1) read the file and send it to the client, then (2) log the
request. Exactly which phases are processed and how varies greatly and
depends on the configuration.

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

\indexii{generic}{handler}
The most commonly used handler is \code{PythonHandler}. It handles the
phase of the request during which the actual content is provided. We
will refer to this handler from here on as \dfn{generic} handler. The
default Apache action for this handler would be to read the file and
send it to the client. Most applications you will write will use this
one handler. If you insist on seeing 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}
<Directory /mywebdir>
    AddHandler python-program .py
    PythonHandler myscript
</Directory>
\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}
    from mod_python import apache

    def handler(req):

        req.content_type = "text/plain"
        req.send_http_header()
        req.write("Hello World!")

        return apache.OK
\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.

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 \samp{PythonHandler
myscript} directive and do the following:

\begin{enumerate}

\item
If not already done, prepend the directory in which the
\code{PythonHandler} directive was found to \code{sys.path}.

\item
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}.

\item
Call the function, passing it a \class{Request} object. (More on what a
\class{Request} object is later)

\item
At this point we're inside the script: 

\begin{itemize}

\item
\begin{verbatim}
from mod_python import apache
\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}
def handler(req):
\end{verbatim}

\index{handler}
This is our \dfn{handler} function declaration. It is called
\code{"handler"} because mod_python takes the name of the directive,
converts it to lower case and removes the word \code{"python"}. Thus
\code{"PythonHandler"} becomes \code{"handler"}. You could name it 
something else, and specify it explicitly in the directive using the
special \samp{::} notation. 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 mysterious
\class{Request} object. There is really no mystery about it though.  The
\class{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 \class{Request} object, i.e. there is no "response" object.

\item
\begin{verbatim}
    req.content_type = "text/plain"
\end{verbatim}

This sets the content type to \code{"text/plain"}. The default is usually
\code{"text/html"}, but since our handler doesn't produce any html,
\code{"text/plain"} is more appropriate.

\item
\begin{verbatim}
    req.send_http_header()
\end{verbatim}

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 \code{"Content-Type"}. So if you want to set
custom content-types, you better do it before you call
\code{req.send_http_header()}.

\item
\begin{verbatim}
    req.write("Hello Wordl!")
\end{verbatim}

This writes the \code{"Hello World!"} string to the client. (Did I really
have to explain this one?)

\item
\begin{verbatim}
    return apache.OK
\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
nowhere did it say that in order for all of the above to happen, 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.

 \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 "spam", and the password to be "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}
<Directory /mywebdir>
    AddHandler python-program .py
    PythonHandler myscript
    PythonAuthenHandler myscript
</Directory>
\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 I'm not going to go into details here). Our config
looks like this now:

\begin{verbatim}
<Directory /mywebdir>
    AddHandler python-program .py
    PythonHandler myscript
    PythonAuthenHandler myscript
    AuthType Basic
    AuthName "Restricted Area"
    require valid-user
</Directory>
\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}
def authenhandler(req):

    pw = req.get_basic_auth_pw()
    user = req.connection.user     
    if user == "spam" and pw == "eggs":
        return apache.OK
    else:
        return apache.HTTP_UNAUTHORIZED
\end{verbatim}  

Let's look at this line by line: 

\begin{itemize}

\item
\begin{verbatim}
def authenhandler(req):
\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
"Python" and converts it lower case.

\item
\begin{verbatim}
    pw = req.get_basic_auth_pw()
\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.

\item
\begin{verbatim}
    user = req.connection.user
\end{verbatim}
                  
This is how you obtain the username that the user entered. In case
you're wondering, the \member{connection} member of the \class{Request}
object is an object that contains information specific to a
\dfn{connection}. With HTTP Keep-Alive, a single connection
can serve multiple requests.

\strong{NOTE:} The two lines above MUST be in that order. The reason is that
\code{connection.user} is assigned a value by the \method{get_basic_auth_pw()}
function. If you try to use the \code{connection.user} value without calling
\method{get_basic_auth_pw()} first, it will be \constant{None}.

\item
\begin{verbatim}
    if user == "spam" and pw == "eggs":
        return apache.OK
\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 proceed to the next handler. (which in
this case would be \function{handler()} if it's a \code{.py} file).

\item
\begin{verbatim}
    else:
        return apache.HTTP_UNAUTHORIZED 
\end{verbatim}

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

\end{itemize}

\section{Publisher Handler Makes it Easy\label{tut-pub}}

At this point you may be wondering if mod_python is all that useful
after all. You may find yourself asking: "If there can only be one
handler per directory, how am I to structure my application?"

Enter the \code{publisher} handler 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}
AddHandler python-program .py
PythonHandler mod_python.publisher
\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 the
will construct an e-mail to the webmaster using the information
submitted by the user.

Here is the html for the form:

\begin{verbatim}
<html>
  Please provide feedback below:
  <p>                           
  <form action="form/email" method="POST">

    Name: <input type="text" name="name"><br>
    Email: <input type="text" name="email"><br>
    Comment: <textarea name="comment" rows=4 cols=20></textarea><br>
    <input type="submit">

  </form>
</html>  
\end{verbatim}

Note the \code{action} element of the \code{<form>} tag points to
\code{form/email}. We are going to create a file called \filenq{form.py},
like this:

\begin{verbatim}

import smtplib

def email(req, name, email, comment):

    # see if the user provided all the parameters
    if not (name and email and comment):
        return "A required parameter is missing, \
please go back and correct the error"

    # create the message text
    msg = """\
From: %s
Subject: feedback
To: webmaster

I have the following comment:

%s

Thank You,

%s

""" % (email, comment, name)

    # send it out
    conn = smtplib.SMTP("localhost")
    conn.sendmail(email, ["webmaster"], msg)
    conn.quit()

    # provide feedback to the user
    s = """\
<html>

Dear %s,<br>

Thank You for your kind comments, we
will get back to you shortly.

</html>""" % name

    return s
\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. Note that it will
also pass the \class{Request} object as \code{req}.  Note also 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.

Also notice how it sends data back to the customer - via the return
value of the function. 

And last, but not the least, note how all the power of mod_python
is still available to this function, since it has access to the
\class{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.