%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright 2001 by Object Craft P/L, Melbourne, Australia.
% LICENCE - see LICENCE file distributed with this software for details.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Prepackaged Application and Execution Context Classes\label{pack-overview}}

\begin{figure}[h]
\begin{center}
\includegraphics{AlbatrossObjects}
\caption{Albatross Classes}
\end{center}
\end{figure}

\section{The \texttt{SimpleContext} Execution Context\label{pack-simplecontext}}

The \texttt{SimpleContext} class is provided for applications which
only make use of the Albatross template functionality.  If you look at
the implementation of the class you will note that it is constructed
from a number of mixin classes.  Each of these classes implements some
of the functionality required for interpreting Albatross templates.

Diagrammatically the \texttt{SimpleContext} class looks like this:

\begin{figure}[h]
\index{\class{SimpleContext}}
\begin{center}
\includegraphics{simplecontext}
\caption{The \class{SimpleContext} class\label{fig-simplecontext}}
\end{center}
\end{figure}

By implementing the execution context semantics in a collection of
mixin classes Albatross allows you to change semantics by substituting
mixins which implement the same interface.  This is very useful when
using the Albatross application objects.

\begin{description}
\item{\class{NamespaceMixin}}
This mixin provides a local namespace for evaluating the expressions
embedded in the \texttt{expr} tag attributes.  Application code places
values into the \member{locals} member to make them available for
display by the template files.

You will probably always use this mixin in your execution context.

\item{\class{ExecuteMixin}}
This mixin provides a sort of virtual machine which is required by the
template file interpreter.  It maintains a macro argument stack for
expanding macros, and it is used to accumulate HTML produced by
template execution.

You will probably always use this mixin in your execution context.

\item{\class{ResourceMixin}}
This mixin provides a registry of template resources which only need
to be defined once.  Specifically the class provides a dictionary of
Python classes which implement template file tags, a dictionary of
template macros, and a dictionary of template lookup tables.

If you are using Albatross application functionality, you will almost
certainly use this mixin in your application class, not the execution
context.

\item{\class{TemplateLoaderMixin}}
This mixin is a very simple template file loader.  You will almost
certainly use the \class{CachingTemplateLoaderMixin} in your
application object instead of this mixin when you use the Albatross
application objects.

\item{\class{StubRecorderMixin}}
Albatross provides special versions of the standard HTML
\texttt{<input>}, \texttt{<select>}, and \texttt{<form>} tags.  As
these tags are converted to HTML they report back to the execution
context.  Applications which do not need to record the contents of
each form can use this mixin to ignore the form record.

\item{\class{StubSessionMixin}}

Albatross provides an application session.  Applications which do not
a session can use this mixin to disable session functionality.
\end{description}

Collectively these classes provide all of the functionality which is
required to execute Albatross templates.  The following table contains
a list of all methods defined in the context.

\input{SimpleContext-methods}

Looking inside the \module{context} module you will notice some mixin
classes which provide alternatives for some of the context
functionality.  The \class{CachingTemplateLoaderMixin} class can be
used to replace the \class{TemplateLoaderMixin}.  Likewise the
\class{NameRecorderMixin} class is a drop-in replacement for the
\class{StubRecorderMixin} class.  These alternatives are used by some
of the prepackaged application objects.

Although all of the template file examples in the Templates User Guide
used the \class{SimpleContext} class as the execution context, you are
much more likely to use something derived from the \class{AppContext}
class defined in the \module{app} module.  Since Albatross creates a
new execution context to process each browser request, it makes sense
to manage tag classes, macros, and lookup tables somewhere other than
in the execution context.

\section{The \texttt{AppContext} Base Class\label{pack-appcontext}}

All execution contexts used by Albatross application classes are
derived from the \class{AppContext} class.  The class acts as a proxy
and redirects all \class{ResourceMixin} and \class{TemplateLoader}
class methods to the application object.  This allows the application
to cache resources so that they do not need to be defined for every
request.

The class places very few assumptions about how you wish to structure
and deploy your application and is suitable as a base class for all
application execution context classes.

\begin{figure}[!h]
\index{\class{AppContext}}
\begin{center}
\includegraphics{appcontext}
\caption{The \class{AppContext} class\label{fig-appcontext}}
\end{center}
\end{figure}

The methods available in \class{AppContext} and the location of their
definition are show below.

\input{AppContext-methods}

There are a number of new methods and attributes introduced by the
class.

\begin{methoddesc}[AppContext]{__init__}{app}
When you inherit from the \class{AppContext} class you must call
this constructor.

The \var{app} argument specifies the application object.  This is
saved in the \member{app} member.
\end{methoddesc}

\begin{memberdesc}[AppContext]{app}
Stores the \var{app} argument to the constructor.
\end{memberdesc}

\begin{methoddesc}[AppContext]{get_macro}{name}
Returns the result of the \method{get_macro()} method of the
application in the \member{app} member.
\end{methoddesc}

\begin{methoddesc}[AppContext]{register_macro}{name, macro}
Returns the result of the \method{register_macro()} method of the
application in the \member{app} member.
\end{methoddesc}

\begin{methoddesc}[AppContext]{get_lookup}{name}
Returns the result of the \method{get_lookup()} method of the
application in the \member{app} member.
\end{methoddesc}

\begin{methoddesc}[AppContext]{register_lookup}{name, lookup}
Returns the result of the \method{register_lookup()} method of the
application in the \member{app} member.
\end{methoddesc}

\begin{methoddesc}[AppContext]{get_tagclass}{name}
Returns the result of the \method{get_tagclass()} method of the
application in the \member{app} member.
\end{methoddesc}

\begin{methoddesc}[AppContext]{load_template}{name}
Returns the result of the \method{load_template()} method of the
application in the \member{app} member.
\end{methoddesc}

\begin{methoddesc}[AppContext]{load_template_once}{name}
Returns the result of the \method{load_template_once()} method of the
application in the \member{app} member.
\end{methoddesc}

\begin{methoddesc}[AppContext]{run_template}{name}
Calls the application \method{load_template()} method to load the
template specified in the \var{name} argument and sets the execution
context global namespace to the globals of the function which called
this method.  The template \method{to_html()} method is then called to
execute the template.
\end{methoddesc}

\begin{methoddesc}[AppContext]{run_template_once}{name}
Calls the application \method{load_template_once()} method.  If the
template specified in the \var{name} argument is loaded or reloaded
the method sets the execution context global namespace to the globals
of the function which called this method, then the template
\method{to_html()} method is then called to execute the template.
\end{methoddesc}

\begin{methoddesc}[AppContext]{clear_locals}{}
Overrides the \class{NamespaceMixin} \method{clear_locals()} method to
retain the \member{__page__} local namespace value.
\end{methoddesc}

\begin{methoddesc}[AppContext]{set_page}{name \optional{, \ldots}}
Sets the current application page to that specified in the \var{name}
argument.  If changing pages and there is a current page defined then
before changing pages the \function{page_leave()} function/method will
be called for the current page.  The \member{locals.__page__} member
is then set to \var{name} and the new page is loaded.  Any addition
arguments passed to the method will be passed to the
\function{page_enter()} function/method code which is associated with
the new page.

Refer to page \pageref{mixin-page} in section \ref{mixin-page} for an
explanation of page functions/methods.
\end{methoddesc}

\begin{methoddesc}[AppContext]{push_page}{name \optional{, \ldots}}
Pushes an application page onto the page stack. The current page
can be returned to by calling the \method{pop_page()} method. The
\function{page_leave()} function/method of the current page is not
called. The new page is loaded and it's \function{page_enter()}
function/method is called. Any additional arguments given will be
passed to the \function{page_enter()} function/method associated with
the new page.
\end{methoddesc}

\begin{methoddesc}[AppContext]{pop_page}{}
Pops the current page from the page stack and returns to the page
that was current when the \method{push_page()} method was called. The
\function{page_leave()} function/method of the current page is called
prior to loading the original page. The \function{page_enter()}
function/method of the original page is not called.
\end{methoddesc}

\begin{methoddesc}[AppContext]{set_request}{req}
Saves the browser request specified in the \var{req} argument as the
\member{request}.
\end{methoddesc}

\begin{methoddesc}[AppContext]{req_equals}{name}
Returns whether or not the browser request contains a non-empty field
with a name which matches the \var{name} argument.
\end{methoddesc}

\begin{methoddesc}[AppContext]{base_url}{}
Returns the result of the application \method{base_url()} method.
\end{methoddesc}

\begin{methoddesc}[AppContext]{current_url}{}
Returns the path component (see the standard \module{urlparse} module)
of the URI used to request the current page.
\end{methoddesc}

\begin{methoddesc}[AppContext]{absolute_base_url}{}
Returns the \var{base_url} parameter to the application constructor
transformed into an absolute URL.
\end{methoddesc}

\begin{methoddesc}[AppContext]{redirect_url}{loc}
Returns an absolute URL for the application page identifier specified
in the \var{loc} parameter.
\end{methoddesc}

\begin{methoddesc}[AppContext]{redirect}{loc}
Raises a \exception{Redirect} exception requesting a redirect to the
location in the \var{loc} parameter from the application
\method{run()} method.

If the \var{loc} parameter contains either a scheme or netloc (from
the standard \module{urlparse} module), or begins with a ``/'' then is
it used without modification for the \exception{Redirect} exception.
Other forms of \var{loc} are assumed to be page identifiers and are
passed to \method{redirect_url()} before being raised as a
\exception{Redirect} exception.
\end{methoddesc}

\section{Context classes:\label{pack-contextclasses}}

\subsection{The \texttt{SimpleAppContext} Class\label{pack-simpleappcontext}}

The \class{SimpleAppContext} class is intended to be used for
applications which store state at the browser in hidden HTML fields.
An inheritance diagram illustrates the relationship to the
\class{SimpleContext} class described above.

\begin{figure}[!h]
\index{\class{SimpleAppContext}}
\begin{center}
\includegraphics{simpleappcontext}
\caption{The \class{SimpleAppContext} class\label{fig-simpleappcontext}}
\end{center}
\end{figure}

The methods available in \class{SimpleAppContext} and the location of their
definition are show below.

\input{SimpleAppContext-methods}

The \class{SimpleAppContext} class provides the following
functionality to your application.

\begin{itemize}
\item
Application state is stored inside hidden fields in the HTML.

This function is performed by the \class{HiddenFieldSessionMixin} mixin
class which places a hidden field named \texttt{__albstate__} inside
each HTML form constructed using \texttt{<al-form>} tags.  The session
data is pickled, compressed, then base64 encoded.  No encryption is
performed, so this is not suitable for storing sensitive data.

If you refer back to the Albatross application processing sequence
described in section \ref{app-proc-seq} you will note where the
session is loaded into and saved from the context.  These steps
correspond to the \method{load_session()} and \method{save_session()}
methods of the execution context respectively.

In the \class{HiddenFieldSessionMixin} class, the
\method{load_session()} method retrieves the encoded session data from
the \texttt{__albstate__} field in the browser request.  The
\method{save_session()} method does not do anything because the
session has already been saved into each form produced in the HTML
output.

\item
All input fields in an HTML form which are left empty by the browser
will be set to \code{None} when the request is merged into the local
namespace.

The \class{NameRecorderMixin} mixin class encodes the names of all
\texttt{<al-input>} fields in the form inside a hidden field named
\texttt{__albform__}.

Any input field which is left empty in the browser when the form is
submitted will not exist in the browser request to the server.  When
the toolkit merges the browser request into the application context,
the \texttt{__albform__} field is used to detect the fields missing
from the browser request.
\end{itemize}

The methods implemented in the \class{SimpleAppContext} class are:

\begin{methoddesc}[SimpleAppContext]{__init__}{app}
When you inherit from the \class{SimpleAppContext} class you must call
this constructor.

The \var{app} argument is passed to the \class{AppContext}
constructor.
\end{methoddesc}

\begin{methoddesc}[SimpleAppContext]{form_close}{}
Invokes the \method{form_close()} method of the
\class{NameRecorderMixin} class and \method{encode_session()} of the
\class{HiddenFieldSessionMixin} class.
\end{methoddesc}

\subsection{The \texttt{SessionAppContext} Class\label{pack-sessappcontext}}

The \class{SessionAppContext} class is intended to be used for
applications which store state at the server.  An inheritance diagram
illustrates the relationship to the \class{SimpleAppContext} class
described above.

\begin{figure}[h]
\index{\class{SessionAppContext}}
\begin{center}
\includegraphics{sessionappcontext}
\caption{The \class{SessionAppContext} class\label{fig-sessappcontext}}
\end{center}
\end{figure}

The methods available in \class{SessionAppContext} and the location of
their definition are show below.

\input{SessionAppContext-methods}

Externally the execution context is almost identical to that of the
\class{SimpleAppContext} class.  Instead of saving session data in
hidden HTML fields, session data is loaded and saved via a session
server which is managed by the application.

The class defines a number of extra methods.

\begin{methoddesc}[SessionAppContext]{__init__}{app}
When you inherit from the \class{SessionAppContext} class you must
call this constructor.

The \var{app} argument is passed to the \class{AppContext}
constructor.
\end{methoddesc}

\subsection{The \texttt{SessionFileAppContext} Class\label{pack-sessfileappcontext}}

The \class{SessionFileAppContext} class is intended to be used for
applications which store state at the server.  An inheritance diagram
illustrates the relationship to the \class{SimpleAppContext} class
described above.

\begin{figure}[h]
\index{\class{SessionFileAppContext}}
\begin{center}
\includegraphics{sessionfileappcontext}
\caption{The \class{SessionFileAppContext} class\label{fig-sessfileappcontext}}
\end{center}
\end{figure}

The methods available in \class{SessionFileAppContext} and the
location of their definition are show below.

\input{SessionFileAppContext-methods}

Externally the execution context is almost identical to that of the
\class{SimpleAppContext} class.  Instead of saving session data in
hidden HTML fields, session data is loaded and saved to the servers
local file system, which is managed by the application.

The class defines a number of extra methods.

\begin{methoddesc}[SessionFileAppContext]{__init__}{app}
When you inherit from the \class{SessionFileAppContext} class you must
call this constructor.

The \var{app} argument is passed to the \class{AppContext}
constructor.
\end{methoddesc}

\subsection{The \texttt{BranchingSessionContext} Class\label{pack-branchingsesscontext}}

The \class{BranchingSessionContext} class is intended to be used with
the server-side session application classes. It creates a new session for
each interaction with the client, and stores the session identifier in a
hidden form field. This allows us to detect when the browser state
rolls back (via the browser \texttt{back} button), and find the
appropriate session context, giving an effect like the client-side
\class{SimpleAppContext} without storing the entire context in a hidden
form field.

\begin{figure}[h]
\index{\class{BranchingSessionContext}}
\begin{center}
\includegraphics{branchingsessioncontext}
\caption{The \class{BranchingSessionContext} class\label{fig-branchingsessioncontext}}
\end{center}
\end{figure}

The methods available in \class{BranchingSessionContext} and the
location of their definition are show below.

\input{BranchingSessionContext-methods}

Externally the execution context is almost identical to that of the
SimpleAppContext class. Instead of saying the session data in hidden
HTML fields, the session identifier is stored in a hidden field, and
the session data is saved and loaded from the session server.

The class defines a number of extra methods:

\begin{methoddesc}[BranchingSessionContext]{__init__}{app}
When you inherit from the \class{BranchingSessionContext} class you must
call this constructor.

The \var{app} argument is passed to the \class{AppContext}
constructor.
\end{methoddesc}

\begin{methoddesc}[BranchingSessionContext]{form_close}{}
Invokes the \method{form_close()} method of the
\class{NameRecorderMixin} class and \method{encode_session()} of the
\class{BranchingSessionMixin} class.
\end{methoddesc}

\section{The \texttt{Application} Base Class\label{pack-app}}

The \class{Application} class is the base class for all Albatross
application objects.

The class inherits from the \class{ResourceMixin} class to allow all
application resources to be loaded once and used for every browser
request.  The \class{AppContext} class directs all resource related
execution context method here.

\begin{figure}[!h]
\index{\class{Application}}
\begin{center}
\includegraphics{application}
\caption{The \class{Application} class\label{fig-application}}
\end{center}
\end{figure}

The methods available in \class{Application} and the location of their
definition are show below.

\input{Application-methods}

The \class{Application} class introduces a number of new methods.

\begin{methoddesc}[Application]{__init__}{base_url}
When you inherit from the \class{Application} class you must call this
constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.
\end{methoddesc}

\begin{methoddesc}[Application]{base_url}{}
Returns the \var{base_url} argument which was passed to the
constructor.
\end{methoddesc}

\begin{methoddesc}[Application]{run}{req}
Implements the standard application run sequence as described on page
\pageref{app-proc-seq} in section \ref{app-proc-seq}.  The browser
request passed as the \var{req} argument is attached to the execution
context as soon as the context has been created.

If an exception is caught then the \method{handle_exception()} method
is called passing the \var{req} argument.
\end{methoddesc}

\begin{methoddesc}[Application]{format_exception}{}
Retrieves the current exception from \code{sys.exc_info()} then
formats and returns the standard Python traceback and a template
interpreter traceback.
\end{methoddesc}

\begin{methoddesc}[Application]{handle_exception}{ctx, req}
This implements the default exception handling for applications.  The
\var{req} argument is the browser request which was passed to the
\method{run()} method.

The method calls the \method{format_exception()} method to construct a
standard Python traceback and a template traceback.  A temporary
execution context is then created, the Python traceback is saved in
the \member{locals.python_exc} value, and the template traceback in
the \member{locals.html_exc} value.

The method then tries to load the \texttt{'traceback.html'} template
file and execute it with the temporary execution context.  This gives
you the ability to control the presentation and reporting of
exceptions.

If any exceptions are raised during the execution of
\texttt{'traceback.html'} the method writes both formatted exceptions
as a \texttt{<pre>} formatted browser response.
\end{methoddesc}

\begin{methoddesc}[Application]{template_traceback}{tb}
Generates a template interpreter traceback from the Python stack trace
in the \var{tb} argument.
\end{methoddesc}

\begin{methoddesc}[Application]{load_session}{ctx}
Calls the \method{load_session()} method of the execution context in
the \var{ctx} argument.
\end{methoddesc}

\begin{methoddesc}[Application]{save_session}{ctx}
Calls the \method{save_session()} method of the execution context in
the \var{ctx} argument.
\end{methoddesc}

\begin{methoddesc}[Application]{remove_session}{ctx}
Calls the \method{remove_session()} method of the execution context in
the \var{ctx} argument.
\end{methoddesc}

\begin{methoddesc}[Application]{validate_request}{ctx}
Returns \code{TRUE}.

You should override this method in your application object if you need
to validate browser requests before processing them.
\end{methoddesc}

\begin{methoddesc}[Application]{pickle_sign}{text}
Returns an empty string to prevent insecure pickles being sent to the
browser.  This is overridden in the \class{PickleSignMixin} class.
\end{methoddesc}

\begin{methoddesc}[Application]{pickle_unsign}{text}
Returns an empty string to prevent insecure pickles being accepted
from the browser.  This is overridden in the \class{PickleSignMixin}
class.
\end{methoddesc}

\begin{methoddesc}[Application]{merge_request}{ctx}
Calls the \method{merge_request()} method of the execution context.
\end{methoddesc}

\section{Application Classes:\label{pack-appclasses}}

\subsection{The \texttt{SimpleApp} Class\label{pack-simpleapp}}

The \class{SimpleApp} class is intended for use in monolithic
applications (page objects instead of page modules).  An inheritance
diagram illustrates the relationship to the \class{SimpleAppContext}
class described above.

\begin{figure}[!h]
\index{\class{SimpleApp}}
\begin{center}
\includegraphics{simpleapp}
\caption{The \class{SimpleApp} class\label{fig-simpleapp}}
\end{center}
\end{figure}

The methods available in \class{SimpleApp} and the location of their
definition are show below.

\input{SimpleApp-methods}

The  \class{SimpleApp} class defines the following methods:

\begin{methoddesc}[SimpleApp]{__init__}{base_url, template_path, start_page, secret}
When you inherit from the \class{SimpleApp} class you must call this
constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The
\var{template_path} defines the root directory where template files
are loaded from.  The \var{start_page} identifies the first page that
will be served up in a new browser session.  The \var{secret} argument
is used to MD5 sign all pickles sent to the browser.
\end{methoddesc}

\begin{methoddesc}[SimpleApp]{create_context}{}
Returns a new instance of the \class{SimpleAppContext} class.
\end{methoddesc}

\subsection{The \texttt{SimpleSessionApp} Class\label{pack-simplesessapp}}

The \class{SimpleSessionApp} class is intended for use in monolithic
applications (page objects instead of page modules).  Session state is
stored at the server.

\begin{figure}[!h]
\index{\class{SimpleSessionApp}}
\begin{center}
\includegraphics{simplesessapp}
\caption{The \class{SimpleSessionApp} class\label{fig-simplesessapp}}
\end{center}
\end{figure}

The methods available in \class{SimpleSessionApp} and the location of
their definition are show below.

\input{SimpleSessionApp-methods}

The \class{SimpleSessionApp} class defines the following methods:

\begin{methoddesc}[SimpleSessionApp]{__init__}{base_url, template_path, start_page, secret, session_appid \optional{, session_server \code{= 'localhost'}} \optional{, server_port \code{= 34343}} \optional{, session_age \code{= 1800}}}
When you inherit from the \class{SimpleSessionApp} class you must call
this constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The
\var{template_path} defines the root directory where template files
are loaded from.  The \var{start_page} identifies the first page that
will be served up in a new browser session.  The \var{secret} argument
is used to MD5 sign all pickles sent to the browser.

The \var{session_appid} argument identifies the session application at
the session server.  Multiple applications can share sessions by using
the same identifier here.  The \var{session_server} argument defines
the host where the session server is running, it defaults to
\texttt{localhost}.  The \var{server_port} defines the session server
port, it defaults to \code{34343}.  The \var{session_age} argument
defines the number of seconds that an idle session will be kept, it
defaults to \code{1800}.
\end{methoddesc}

\begin{methoddesc}[SimpleSessionApp]{create_context}{}
Returns a new instance of the \class{SessionAppContext} class.
\end{methoddesc}

\subsection{The \texttt{SimpleSessionFileApp} Class\label{pack-simplesessfileapp}}

The \class{SimpleSessionFileApp} class is intended for use in monolithic
applications (page objects instead of page modules).  Session state is
stored in the file system at the server.

\begin{figure}[!h]
\index{\class{SimpleSessionFileApp}}
\begin{center}
\includegraphics{simplesessfileapp}
\caption{The \class{SimpleSessionFileApp} class\label{fig-simplesessfileapp}}
\end{center}
\end{figure}

The methods available in \class{SimpleSessionFileApp} and the location of their
definition are show below.

\input{SimpleSessionFileApp-methods}

The \class{SimpleSessionFileApp} class defines the following methods:

\begin{methoddesc}[SimpleSessionFileApp]{__init__}{base_url, template_path, start_page, secret, session_appid, session_dir}
When you inherit from the \class{SimpleSessionFileApp} class you must call
this constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The
\var{template_path} defines the root directory where template files
are loaded from.  The \var{start_page} identifies the first page that
will be served up in a new browser session.  The \var{secret} argument
is used to MD5 sign all pickles sent to the browser.

The \var{session_appid} argument identifies the session application in the
browser cookie. Multiple applications can share sessions by using
the same identifier here.  The \var{session_dir} argument defines
the directory in which the application will store session files.
\end{methoddesc}

\begin{methoddesc}[SimpleSessionFileApp]{create_context}{}
Returns a new instance of the \class{SessionFileAppContext} class.
\end{methoddesc}

\subsection{The \texttt{ModularApp} Class\label{pack-modularapp}}

The \class{ModularApp} class is intended for use in applications which
define page code in a collection of Python modules.

\begin{figure}[!h]
\index{\class{ModularApp}}
\begin{center}
\includegraphics{modularapp}
\caption{The \class{ModularApp} class\label{fig-modularapp}}
\end{center}
\end{figure}

The methods available in \class{ModularApp} and the location of their
definition are show below.

\input{ModularApp-methods}

The \class{ModularApp} class defines the following methods:

\begin{methoddesc}[ModularApp]{__init__}{base_url, module_path, template_path, start_page, secret}
When you inherit from the \class{ModularApp} class you must call this
constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The
\var{module_path} argument defines the root directory where page
modules are loaded from.  The \var{template_path} argument defines the
root directory where template files are loaded from.  The
\var{start_page} identifies the first page that will be served up in a
new browser session.  The \var{secret} argument is used to MD5 sign
all pickles sent to the browser.
\end{methoddesc}

\begin{methoddesc}[ModularApp]{create_context}{}
Returns a new instance of the \class{SimpleAppContext} class.
\end{methoddesc}

\subsection{The \texttt{ModularSessionApp} Class\label{pack-modularsessapp}}

The \class{ModularSessionApp} class is intended for use in
applications which define page code in a collection of Python modules.
Session state is stored at the server.

\begin{figure}[!h]
\index{\class{ModularSessionApp}}
\begin{center}
\includegraphics{modularsessapp}
\caption{The \class{ModularSessionApp} class\label{fig-modularsessapp}}
\end{center}
\end{figure}

The methods available in \class{ModularSessionApp} and the location of
their definition are show below.

\input{ModularSessionApp-methods}

The \class{ModularSessionApp} class defines the following methods:

\begin{methoddesc}[ModularSessionApp]{__init__}{base_url, module_path, template_path, start_page, secret, session_appid \optional{, session_server \code{= 'localhost'}} \optional{, server_port \code{= 34343}} \optional{, session_age \code{= 1800}}}
When you inherit from the \class{ModularSessionApp} class you must call
this constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The
\var{module_path} argument defines the root directory where page
modules are loaded from.  The \var{template_path} argument defines the
root directory where template files are loaded from.  The
\var{start_page} identifies the first page that will be served up in a
new browser session.  The \var{secret} argument is used to MD5 sign
all pickles sent to the browser.

The \var{session_appid} argument identifies the session application at
the session server.  Multiple applications can share sessions by using
the same identifier here.  The \var{session_server} argument defines
the host where the session server is running, it defaults to
\texttt{localhost}.  The \var{server_port} defines the session server
port, it defaults to \code{34343}.  The \var{session_age} argument
defines the number of seconds that an idle session will be kept, it
defaults to \code{1800}.
\end{methoddesc}

\begin{methoddesc}[ModularSessionApp]{create_context}{}
Returns a new instance of the \class{SessionAppContext} class.
\end{methoddesc}

\subsection{The \texttt{ModularSessionFileApp} Class\label{pack-modularsessfileapp}}

The \class{ModularSessionFileApp} class is intended for use in
applications which define page code in a collection of Python modules.
Session state is stored in the file system at the server.

\begin{figure}[!h]
\index{\class{ModularSessionFileApp}}
\begin{center}
\includegraphics{modularsessfileapp}
\caption{The \class{ModularSessionFileApp} class\label{fig-modularsessfileapp}}
\end{center}
\end{figure}

The methods available in \class{ModularSessionFileApp} and the
location of their definition are show below.

\input{ModularSessionFileApp-methods}

The \class{ModularSessionFileApp} class defines the following methods:

\begin{methoddesc}[ModularSessionFileApp]{__init__}{base_url, module_path, template_path, start_page, secret, session_appid, session_dir}
When you inherit from the \class{ModularSessionFileApp} class you must call
this constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The
\var{module_path} argument defines the root directory where page
modules are loaded from.  The \var{template_path} argument defines the
root directory where template files are loaded from.  The
\var{start_page} identifies the first page that will be served up in a
new browser session.  The \var{secret} argument is used to MD5 sign
all pickles sent to the browser.

The \var{session_appid} argument identifies the session application in the
browser cookie. Multiple applications can share sessions by using
the same identifier here.  The \var{session_dir} argument defines
the directory in which the application will store session files.
\end{methoddesc}

\begin{methoddesc}[ModularSessionFileApp]{create_context}{}
Returns a new instance of the \class{SessionFileAppContext} class.
\end{methoddesc}

\subsection{The \texttt{RandomModularApp} Class\label{pack-ranmodapp}}

The \class{RandomModularApp} class is intended for use in applications
which define page code in a collection of Python modules which are
randomly accessed via the URI in the browser request.

\begin{figure}[!h]
\index{\class{RandomModularApp}}
\begin{center}
\includegraphics{randmodapp}
\caption{The \class{RandomModularApp} class\label{fig-randmodapp}}
\end{center}
\end{figure}

The methods available in \class{RandomModularApp} and the location of
their definition are show below.

\input{RandomModularApp-methods}

The \class{RandomModularApp} class defines the following methods:

\begin{methoddesc}[RandomModularApp]{__init__}{base_url, page_path, start_page, secret}
When you inherit from the \class{RandomModularApp} class you must call
this constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The \var{page_path}
argument defines the root directory where page modules and template
files are loaded from.  The \var{start_page} identifies the page that
will be served up when a page identifier cannot be determined from the
URI in the browser request.  The \var{secret} argument is used to MD5
sign all pickles sent to the browser.
\end{methoddesc}

\begin{methoddesc}[RandomModularApp]{create_context}{}
Returns a new instance of the \class{SimpleAppContext} class.
\end{methoddesc}

\subsection{The \texttt{RandomModularSessionApp} Class\label{pack-ranmodsessapp}}

The \class{RandomModularSessionApp} class is intended for use in
applications which define page code in a collection of Python modules
which are randomly accessed via the URI in the browser request.
Session state is stored at the server.

\begin{figure}[!h]
\index{\class{RandomModularSessionApp}}
\begin{center}
\includegraphics{randmodsessapp}
\caption{The \class{RandomModularSessionApp} class\label{fig-randmodsessapp}}
\end{center}
\end{figure}

The methods available in \class{RandomModularSessionApp} and the
location of their definition are show below.

\input{RandomModularSessionApp-methods}

The \class{RandomModularSessionApp} class defines the following
methods:

\begin{methoddesc}[RandomModularSessionApp]{__init__}{base_url, page_path, start_page, secret, session_appid \optional{, session_server \code{= 'localhost'}} \optional{, server_port \code{= 34343}} \optional{, session_age \code{= 1800}}}
When you inherit from the \class{RandomModularSessionApp} class you must call
this constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The \var{page_path}
argument defines the root directory where page modules and template
files are loaded from.  The \var{start_page} identifies the page that
will be served up when a page identifier cannot be determined from the
URI in the browser request.  The \var{secret} argument is used to MD5
sign all pickles sent to the browser.

The \var{session_appid} argument identifies the session application at
the session server.  Multiple applications can share sessions by using
the same identifier here.  The \var{session_server} argument defines
the host where the session server is running, it defaults to
\texttt{localhost}.  The \var{server_port} defines the session server
port, it defaults to \code{34343}.  The \var{session_age} argument
defines the number of seconds that an idle session will be kept, it
defaults to \code{1800}.
\end{methoddesc}

\begin{methoddesc}[RandomModularSessionApp]{create_context}{}
Returns a new instance of the \class{SessionAppContext} class.
\end{methoddesc}

\subsection{The \texttt{RandomModularSessionFileApp} Class\label{pack-ranmodsessfileapp}}

The \class{RandomModularSessionFileApp} class is intended for use in
applications which define page code in a collection of Python modules
which are randomly accessed via the URI in the browser request.
Session state is stored in the file system at the server.

\begin{figure}[!h]
\index{\class{RandomModularSessionFileApp}}
\begin{center}
\includegraphics{randmodsessfileapp}
\caption{The \class{RandomModularSessionFileApp} class\label{fig-randmodsessfileapp}}
\end{center}
\end{figure}

The methods available in \class{RandomModularSessionFileApp} and the
location of their definition are show below.

\input{RandomModularSessionFileApp-methods}

The \class{RandomModularSessionFileApp} class defines the following
methods:

\begin{methoddesc}[RandomModularSessionFileApp]{__init__}{base_url, page_path, start_page, secret, session_appid, session_dir}
When you inherit from the \class{RandomModularSessionFileApp} class you must call
this constructor.

The \var{base_url} argument is used as the base for URLs produced by
the \texttt{<al-a>} and \texttt{<al-form>} tags.  The \var{page_path}
argument defines the root directory where page modules and template
files are loaded from.  The \var{start_page} identifies the page that
will be served up when a page identifier cannot be determined from the
URI in the browser request.  The \var{secret} argument is used to MD5
sign all pickles sent to the browser.

The \var{session_appid} argument identifies the session application at
the session server.  Multiple applications can share sessions by using
the same identifier here.  The \var{session_dir} argument defines the
directory in which the application will store session files.
\end{methoddesc}

\begin{methoddesc}[RandomModularSessionFileApp]{create_context}{}
Returns a new instance of the \class{SessionFileAppContext} class.
\end{methoddesc}