\chapter{Server Side Includes\label{ssi}}

\section{Overview of SSI\label{ssi-overview}}

SSI (Server Side Includes) are directives that are placed in HTML pages,

and evaluated on the server while the pages are being served. They let you

add dynamically generated content to an existing HTML page, without having

to serve the entire page via a CGI program, or other dynamic technology

such as a mod_python handler.

SSI directives have the following syntax:

\begin{verbatim}

\end{verbatim}

It is formatted like an HTML comment, so if you don't have SSI correctly

enabled, the browser will ignore it, but it will still be visible in the

HTML source. If you have SSI correctly configured, the directive will be

replaced with its results.

For a more thorough description of the SSI mechanism and how to enable it,

see the \citetitle[http://httpd.apache.org/docs/2.0/howto/ssi.html]{SSI

tutorial} provided with the Apache documentation.

Version 3.3 of mod_python introduces support for using Python code within

SSI files. Note that mod_python honours the intent of the Apache

\code{IncludesNOEXEC} option to the \code{Options} directive. That is, if

\code{IncludesNOEXEC} is enabled, then Python code within a SSI file will

not be executed.

\section{Using Python Code\label{ssi-python-code}}

The extensions to mod_python to allow Python code to be used in conjunction

with SSI introduces the new SSI directive called 'python'. This directive

can be used in two forms, these being 'eval' and 'exec' modes. In the case

of 'eval', a Python expression is used and it is the result of that

expression which is substituted in place into the page.

\begin{verbatim}

\end{verbatim}

Where the result of the expression is not a string, the value will be

automatically converted to a string by applying \code{str()} to the value.

In the case of 'exec' a block of Python code may be included. For any

output from this code to appear in the page, it must be written back

explicitly as being part of the response. As SSI are processed by an Apache

output filter, this is done by using an instance of the mod_python

\code{filter} object which is pushed into the global data set available to

the code.

\begin{verbatim}

\end{verbatim}

Any Python code within the 'exec' block must have a zero first level

indent. You cannot start the code block with an arbitrary level of indent

such that it lines up with any indenting used for surrounding HTML

elements.

Although the mod_python \code{filter} object is not a true file object, that

it provides the \code{write()} method is sufficient to allow the \code{print}

statement to be used on it directly. This will avoid the need to explicitly

convert non string objects to a string before being output.

\begin{verbatim}

\end{verbatim}

\section{Scope of Global Data\label{ssi-data-scope}}

Multiple instances of 'eval' or 'exec' code blocks may be used within the

one page. Any changes to or creation of global data which is performed

within one code block will be reflected in any following code blocks.

Global data constitutes variables as well as module imports, function and

class definitions.

\begin{verbatim}

\end{verbatim}

The lifetime of any global data is for the current request only. If data

must persist between requests, it must reside in external modules and as

necessary be protected against multithreaded access in the event that a

multithreaded Apache MPM is used.

\section{Pre-propulating Globals\label{ssi-globals}}

Any Python code which appears within the page has to be compiled each time

the page is accessed before it is executed. In other words, the compiled

code is not cached between requests. To limit such recompilation and to

avoid duplication of common code amongst many pages, it is preferable to

pre-populate the global data from within a mod_python handler prior to the

page being processed.

In most cases, a fixup handler would be used for this purpose. For this to

work, first need to configure Apache so that it knows to call the fixup

handler.

\begin{verbatim}

\end{verbatim}

The implementation of the fixup handler contained in \code{_handlers.py}

then needs to create an instance of a Python dictionary, store that in the

mod_python request object as \code{ssi_globals} and then populate that

dictionary with any data to be available to the Python code executing

within the page.

\begin{verbatim}

\end{verbatim}

This is most useful where it is necessary to insert common information such

as headers, footers or menu panes which are dynamically generated into many

pages.

\begin{verbatim}

\end{verbatim}

\section{Conditional Expressions\label{ssi-conditionals}}

SSI allows for some programmability in its own right through the use of

conditional expressions. The structure of this conditional construct is:

\begin{verbatim}

\end{verbatim}

A test condition can be any sort of logical comparison, either comparing

values to one another, or testing the 'truth' of a particular value.

The source of variables used in conditional expressions is distinct from

the set of global data used by the Python code executed within a page.

Instead, the variables are sourced from the \code{subprocess_env} table

object contained within the request object. The values of these variables

can be set from within a page using the SSI 'set' directive, or by a range

of other Apache directives within the Apache configuration files such as

\code{BrowserMatchNoCase} and \code{SetEnvIf}.

To set these variables from within a mod_python handler, the

\code{subprocess_env} table object would be manipulated directly through

the request object.

\begin{verbatim}

\end{verbatim}

If being done from within Python code contained within the page itself, the

request object would first have to be accessed via the filter object.

\begin{verbatim}

\end{verbatim}

\section{Enabling INCLUDES Filter\label{ssi-output-filter}}

SSI is traditionally enabled using the \code{AddOutputFilter} directive in

the Apache configuration files. Normally this would be where the request

mapped to a static file.

\begin{verbatim}

\end{verbatim}

When mod_python is being used, the ability to dynamically enable output

filters for the current request can instead be used. This could be done

just for where the request maps to a static file, but may just as easily be

carried out where the content of a response is generated dynamically. In

either case, to enable SSI for the current request, the

\code{add_output_filter()} method of the mod_python request object would be

used.

\begin{verbatim}

\end{verbatim}

\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. You'll need to adjust your httpd configuration:

\begin{verbatim}

\end{verbatim}

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