\chapter{Standard Handlers\label{handlers}}

\section{Publisher Handler\label{hand-pub}}

The \code{publisher} handler is a good way to avoid writing your own

handlers and focus on rapid application development. It was inspired

by \citetitle[http://www.zope.org/]{Zope} ZPublisher.

\subsection{Introduction\label{hand-pub-intro}}

To use the handler, you need the following lines in your configuration

\begin{verbatim}

\end{verbatim}

This handler allows access to functions and variables within a module

via URL's. For example, if you have the following module, called

\file{hello.py}:

\begin{verbatim}

\end{verbatim}

A URL \code{http://www.mysite.com/hello.py/say} would return

\samp{I am saying NOTHING}. A URL

\code{http://www.mysite.com/hello.py/say?what=hello} would

return \samp{I am saying hello}.

\subsection{The Publishing Algorithm\label{hand-pub-alg}}

The Publisher handler maps a URI directly to a Python variable or

callable object, then, respectively, returns it's string

representation or calls it returning the string representation of the

return value.

\subsubsection{Traversal\label{hand-pub-alg-trav}}

The Publisher handler locates and imports the module specified in the

URI. The module location is determined from the \class{req.filename}

attribute. Before importing, the file extension, if any, is

discarded.

If \class{req.filename} is empty, the module name defaults to

\samp{index}.

Once module is imported, the remaining part of the URI up to the

beginning of any query data (a.k.a. PATH_INFO) is used to find an

object within the module. The Publisher handler \dfn{traverses} the

path, one element at a time from left to right, mapping the elements

to Python object within the module.

If no path_info was given in the URL, the Publisher handler will use

the default value of \samp{index}. If the last element is an object inside

a module, and the one immediately preceding it is a directory

(i.e. no module name is given), then the module name will also default

to \samp{index}.

The traversal will stop and \constant{HTTP_NOT_FOUND} will be returned to

the client if:

\begin{itemize}

Any of the traversed object's names begin with an underscore

(\samp{\_}). Use underscores to protect objects that should not be

accessible from the web.

A module is encountered. Published objects cannot be modules for

security reasons.

\end{itemize}

If an object in the path could not be found, \constant{HTTP_NOT_FOUND}

is returned to the client.

For example, given the following configuration:

\begin{verbatim}

\end{verbatim}

And the following \file{/some/dir/index.py} file:

\begin{verbatim}

\end{verbatim}

Then:

http://www.somehost/index/index will return \samp{We are in index()}

http://www.somehost/index/ will return \samp{We are in index()}

http://www.somehost/index/hello will return \samp{We are in hello()}

http://www.somehost/hello will return \samp{We are in hello()}

http://www.somehost/spam will return \samp{404 Not Found}

\subsubsection{Argument Matching and Invocation\label{hand-pub-alg-args}}

Once the destination object is found, if it is callable and not a

class, the Publisher handler will get a list of arguments that the

object expects. This list is compared with names of fields from HTML

form data submitted by the client via \code{POST} or

\code{GET}. Values of fields whose names match the names of callable

object arguments will be passed as strings. Any fields whose names do

not match the names of callable argument objects will be silently dropped,

unless the destination callable object has a \code{**kwargs} style

argument, in which case fields with unmatched names will be passed in the

\code{**kwargs} argument.

If the destination is not callable or is a class, then its string

representation is returned to the client.

\subsubsection{Authentication\label{hand-pub-alg-auth}}

The publisher handler provides simple ways to control access to

modules and functions.

At every traversal step, the Publisher handler checks for presence of

\method{__auth__} and \method{__access__} attributes (in this order), as

well as \method{__auth_realm__} attribute.

If \method{__auth__} is found and it is callable, it will be called

with three arguments: the \class{Request} object, a string containing

the user name and a string containing the password. If the return

value of

\code{__auth__} is false, then \constant{HTTP_UNAUTHORIZED} is

returned to the client (which will usually cause a password dialog box

to appear).

If \method{__auth__} is a dictionary, then the user name will be

matched against the key and the password against the value associated

with this key. If the key and password do not match,

\constant{HTTP_UNAUTHORIZED} is returned. Note that this requires

storing passwords as clear text in source code, which is not very secure.

\method{__auth__} can also be a constant. In this case, if it is false

(i.e. \constant{None}, \code{0}, \code{""}, etc.), then

\constant{HTTP_UNAUTHORIZED} is returned.

If there exists an \code{__auth_realm__} string, it will be sent

to the client as Authorization Realm (this is the text that usually

appears at the top of the password dialog box).

If \method{__access__} is found and it is callable, it will be called

with two arguments: the \class{Request} object and a string containing

the user name. If the return value of \code{__access__} is false, then

\constant{HTTP_FORBIDDEN} is returned to the client.

If \method{__access__} is a list, then the user name will be matched

against the list elements. If the user name is not in the list,

\constant{HTTP_FORBIDDEN} is returned.

Similarly to \method{__auth__}, \method{__access__} can be a constant.

In the example below, only user \samp{eggs} with password \samp{spam}

can access the \code{hello} function:

\begin{verbatim}

\end{verbatim}

Here is the same functionality, but using an alternative technique:

\begin{verbatim}

\end{verbatim}

Since functions cannot be assigned attributes, to protect a function,

an \code{__auth__} or \code{__access__} function can be defined within

the function, e.g.:

\begin{verbatim}

\end{verbatim}

Note that this technique will also work if \code{__auth__} or

\code{__access__} is a constant, but will not work is they are

a dictionary or a list.

The \code{__auth__} and \code{__access__} mechanisms exist

independently of the standard

\citetitle[dir-handlers-auh.html]{PythonAuthenHandler}. It

is possible to use, for example, the handler to authenticate, then the

\code{__access__} list to verify that the authenticated user is

allowed to a particular function.

\begin{notice}In order for mod_python to access \function{__auth__},

the module containing it must first be imported. Therefore, any

module-level code will get executed during the import even if

\function{__auth__} is false. To truly protect a module from

being accessed, use other authentication mechanisms, e.g. the Apache

\code{mod_auth} or with a mod_python \citetitle[dir-handlers-auh.html]

{PythonAuthenHandler} handler.

\end{notice}

\subsection{Form Data}

In the process of matching arguments, the Publisher handler creates an

instance of \citetitle[pyapi-util-fstor.html]{FieldStorage}

class. A reference to this instance is stored in an attribute \member{form}

of the \class{Request} object.

Since a \class{FieldStorage} can only be instantiated once per

request, one must not attempt to instantiate \class{FieldStorage} when

using the Publisher handler and should use

\class{Request.form} instead.

\section{PSP Handler\label{hand-psp}}

\index{PSP}

PSP handler is a handler that processes documents using the

\class{PSP} class in \code{mod_python.psp} module.

To use it, simply add this to your httpd configuration:

\begin{verbatim}

\end{verbatim}

For more details on the PSP syntax, see Section \ref{pyapi-psp}.

If \code{PythonDebug} server configuration is \code{On}, then by

appending an underscore (\samp{_}) to the end of the url you can get a

nice side-by-side listing of original PSP code and resulting Python

code generated by the \code{psp} module. This is very useful for

debugging.

\begin{notice}

Leaving debug on in a production environment will allow remote users

to display source code of your PSP pages!

\end{notice}

\section{CGI Handler\label{hand-cgi}}

\index{CGI}

CGI handler is a handler that emulates the CGI environment under mod_python.

Note that this is not a \samp{true} CGI environment in that it is

emulated at the Python level. \code{stdin} and \code{stdout} are

provided by substituting \code{sys.stdin} and \code{sys.stdout}, and

the environment is replaced by a dictionary. The implication is that

any outside programs called from within this environment via

\code{os.system}, etc. will not see the environment available to the

Python program, nor will they be able to read/write from standard

input/output with the results expected in a \samp{true} CGI environment.

The handler is provided as a stepping stone for the migration of

legacy code away from CGI. It is not recommended that you settle on

using this handler as the preferred way to use mod_python for the long

term. This is because the CGI environment was not intended for

execution within threads (e.g. requires changing of current directory

with is inherently not thread-safe, so to overcome this cgihandler

maintains a thread lock which forces it to process one request at a

time in a multi-threaded server) and therefore can only be implemented

in a way that defeats many of the advantages of using mod_python in

the first place.

To use it, simply add this to your \file{.htaccess} file:

\begin{verbatim}

\end{verbatim}

As of version 2.7, the cgihandler will properly reload even indirectly

imported module. This is done by saving a list of loaded modules

(sys.modules) prior to executing a CGI script, and then comparing it

with a list of imported modules after the CGI script is done. Modules

(except for whose whose __file__ attribute points to the standard

Python library location) will be deleted from sys.modules thereby

forcing Python to load them again next time the CGI script imports

them.

If you do not want the above behavior, edit the \file{cgihandler.py}

file and comment out the code delimited by \#\#\#.

Tests show the cgihandler leaking some memory when processing a lot of

file uploads. It is still not clear what causes this. The way to work

around this is to set the Apache \code{MaxRequestsPerChild} to a non-zero

value.