%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright 2001 by Object Craft P/L, Melbourne, Australia.
% LICENCE - see LICENCE file distributed with this software for details.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Mixin Class Reference\label{mixin-ref}}

Most of Albatross exists as a collection of plug compatible mixin
classes which you select from to define the way your application
should behave and how it will be deployed.  Figure \ref{fig-toolkit}
shows the organisation of the component types in the toolkit.

\begin{figure}[h]
\begin{center}
\includegraphics{toolkit}
\caption{Toolkit Components\label{fig-toolkit}}
\end{center}
\end{figure}

The divisions in the diagram represent conceptually different
functional areas within the toolkit.

\begin{description}
\item[Templating]

This layer provides the Albatross templating functionality.  Template
classes make use of the methods defined in the next layer down to
access application functionality and data.

Classes in this layer are defined in the \module{albatross.template}
and \module{albatross.tags} modules.

\item[Template Execution]

An execution context suitable for interpreting template files is
constructed by combining one mixin of each type from this layer.

\item[Application Model]

Execution contexts which subclass a \class{PageMixin} class in
addition to the mixins from the above layer are suitable for use in
Albatross applications.  The \class{PageMixin} class controls how the
application locates code and template files for each page served by
the application.  The \class{PickleSignMixin} class is responsible for
modifying pickles which are sent to the browser to prevent or detect
modification.

\item[Your Application]

In this layer you will typically create your own application and
execution context classes by subclassing a prepared application class.

For the most part Albatross applications are independent of the method
by which they are deployed.  Depending upon which \class{Request}
class you choose from this layer you can either deploy your
application via CGI or \texttt{mod_python}.

Each deployment method is implemented in a separate module which is
not imported when you import \module{albatross}.  To use CGI
deployment you import your \class{Request} from
\module{albatross.cgiapp} and to use \texttt{mod_python} deployment
you import from \module{albatross.apacheapp}.
\end{description}

Wherever possible the Albatross mixin classes use member names which
begin with double underscore to trigger Python name mangling.  This
protects your classes from having member name clashes with private
members of the mixin classes.  Any member names which are not mangled
are intended to be accessed in your application code.

\section{ResourceMixin Class\label{mixin-resource}}

Albatross only supplies one class for this function; the
\class{ResourceMixin} class.  This mixin manages application resources
which which do not change regardless of context.  The resources
managed are tag classes, HTML macros, and HTML lookup tables.

The \class{SimpleContext} execution context class subclasses the
\class{ResourceMixin} class.  During the constructor it registers all
of the standard Albatross tags.  As HTML templates are executed the
macros and lookup tables in those templates are registered.

All standard Albatross application classes inherit from the
\class{Application} class which in turn subclasses the
\class{ResourceMixin} class.  During the application class constructor
all of the standard Albatross tags are registered.  The
\class{AppContext} class which is subclassed by all Albatross
application execution context classes proxies all HTML macro and
lookup table methods and directs them to the application object.

\begin{methoddesc}[ResourceMixin]{__init__}{}
When you inherit from the \class{ResourceMixin} class you must call
this constructor to initialise the internal variables.
\end{methoddesc}

\begin{methoddesc}[ResourceMixin]{get_macro}{name}
Returns the macro previously registered by the name in the \var{name}
argument.  If no such macro exists \code{None} is returned.
\end{methoddesc}

\begin{methoddesc}[ResourceMixin]{register_macro}{name, macro}
Registers the HTML macro in the \var{macro} argument under the name in
the \var{name} argument.
\end{methoddesc}

\begin{methoddesc}[ResourceMixin]{get_lookup}{name}
Returns the lookup table previously registered by the name in the
\var{name} argument.  If no such lookup exists \code{None} is
returned.
\end{methoddesc}

\begin{methoddesc}[ResourceMixin]{register_lookup}{name, lookup}
Registers the HTML lookup table in the \var{lookup} argument under the
name in the \var{name} argument.
\end{methoddesc}

\begin{methoddesc}[ResourceMixin]{get_tagclass}{name}
Returns the tag class in which the \member{name} member matches the
name in the \var{name} argument.  If no such tag class exists
\code{None} is returned.
\end{methoddesc}

\begin{methoddesc}[ResourceMixin]{register_tagclasses}{\ldots}
Registers one or more tag classes indexing them by the value in the
\member{name} member of each class.
\end{methoddesc}

\section{ExecuteMixin Class\label{mixin-execute}}

Albatross only supplies one class for this function; the
\class{ExecuteMixin} class.  This mixin provides a ``virtual machine''
which is used to execute HTML template files.

All standard Albatross execution context classes inherit from this
class.

\begin{methoddesc}[ExecuteMixin]{__init__}{}
When you inherit from the \class{ExecuteMixin} class you must call
this constructor to initialise the internal variables.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{get_macro_arg}{name}
Retrieves a macro argument from the macro execution stack.  The stack
is searched from the most recently pushed dictionary for an argument
keyed by \var{name}.  If no argument is found a \exception{MacroError}
exception is raised.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{push_macro_args}{dict}
Pushes a dictionary of macro arguments onto the macro execution stack.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{pop_macro_args}{}
Pops the most recently pushed dictionary of macro arguments from the
macro execution stack.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{push_content_trap}{}
Saves accumulated content on the trap stack and then resets the
content list.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{pop_content_trap}{}
Joins all parts on the content list and returns the result.  Sets the
content list to the value popped off the trap stack.

The content trap is useful for performing out-of-order execution of
template text.  The \texttt{<al-option>} tag makes use of the content
trap.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{write_content}{data}
Appends the content in \var{data} to the content list.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{flush_content}{}
Does nothing if a content trap stack is in effect, otherwise it joins
all parts in the content list and sends it to the browser via the
\method{send_content()} method.  The content list is then reset via
the \method{reset_content()} method.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{flush_html}{}
This is an alias for \method{flush_content()}.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{send_content}{data}
Sends the content passed in the \var{data} argument to standard
output.  This is overridden in the \class{AppContext} class to
redirect \var{data} to the \method{write_content()} method of the
application referenced in the \member{app} member.
\end{methoddesc}

\begin{methoddesc}[ExecuteMixin]{reset_content}{}
Sets the content list to an empty list and clears the content trap
stack.
\end{methoddesc}

\section{ResponseMixin Class\label{mixin-response}}

The \class{ResponseMixin} class provides functionality to manage the
delivery of the application response to the browser.  The class
maintains headers in a case sensitive ordered dictionary that ensures
the headers are sent to the browser in the same sequence as they are
set (via \method{set_header()}).

The class automatically sends the headers to the browser when the
first content is sent.  Any attempt to modify or send headers after
they have been sent will raise an \exception{ApplicationError}
exception.

All Albatross execution context classes except for
\class{SimpleContext} inherit from this class.

\begin{methoddesc}[ResponseMixin]{__init__}{}
When you inherit from the \class{ResponseMixin} class you must call
this constructor to initialise the internal variables.
\end{methoddesc}

\begin{methoddesc}[ResponseMixin]{get_header}{name}
Returns the value of the \var{name} header from the internal store.
If the header does not exist then \code{None} is returned.
\end{methoddesc}

\begin{methoddesc}[ResponseMixin]{set_header}{name, value}
Sets the value of the \var{name} header to \var{value} in the internal
store and updates the header sequence.

If headers have already been sent to the browser then an
\exception{ApplicationError} exception will be raised.
\end{methoddesc}

\begin{methoddesc}[ResponseMixin]{del_header}{name}
Removes the \var{name} header from the internal store.

If headers have already been sent to the browser then an
\exception{ApplicationError} exception will be raised.
\end{methoddesc}

\begin{methoddesc}[ResponseMixin]{write_headers}{}
Writes all headers in ascending sequence to the browser.  Each header
is sent via the \class{Request} object \method{write_header()} method.
At the end of headers the \class{Request} object
\method{end_headers()} method is called.

If headers have already been sent to the browser then an
\exception{ApplicationError} exception will be raised.
\end{methoddesc}

\begin{methoddesc}[ResponseMixin]{send_content}{data}
Sends the content in \var{data} to the browser via the \class{Request}
object \method{write_content()} method.

If headers have not already been delivered to the browser then the
\method{write_headers()} method is called before the \var{data} is
written.
\end{methoddesc}

\begin{methoddesc}[ResponseMixin]{send_redirect}{loc}
If a cookie header has been set it is sent to the browser then the
\method{redirect()} method of the \member{request} member is called
and the result is returned.
\end{methoddesc}

\section{TemplateLoaderMixin Classes\label{mixin-template}}

This mixin is responsible for loading template files.  Albatross
supplies two classes; \class{TemplateLoaderMixin} and
\class{CachingTemplateLoaderMixin}.

\subsection{TemplateLoaderMixin\label{mixin-templ-loader}}

The \class{TemplateLoaderMixin} class is a simplistic loader which
performs no caching.

\begin{methoddesc}[TemplateLoaderMixin]{__init__}{base_dir}
When you inherit from the \class{TemplateLoaderMixin} class you must
call the constructor to define the root directory where template files
will be loaded in the \var{base_dir} argument.
\end{methoddesc}

\begin{methoddesc}[TemplateLoaderMixin]{load_template}{name}
Load and return the parsed template file specified in the \var{name}
argument.  The path to the template file is constructed by performing
\code{os.path.join()} on the \var{base_dir} specified in the
constructor and the \var{name} argument.

If there is an error reading the template a
\exception{TemplateLoadError} will be raised.

The class remembers the names of all loaded templates.
\end{methoddesc}

\begin{methoddesc}[TemplateLoaderMixin]{load_template_once}{name}
Returns \code{None} if the template specified in the \var{name}
argument has been previously loaded.  If not previously loaded it is
loaded via the \method{load_template()} method and returned.
\end{methoddesc}

\subsection{CachingTemplateLoaderMixin\label{mixin-templ-cache}}

The \class{CachingTemplateLoaderMixin} class caches loaded templates
to and only reloads them if they have been modified since they were
last loaded.

\begin{methoddesc}[CachingTemplateLoaderMixin]{__init__}{base_dir}
When you inherit from the \class{CachingTemplateLoaderMixin} class you
must call the constructor to define the root directory where template
files will be loaded in the \var{base_dir} argument.
\end{methoddesc}

\begin{methoddesc}[CachingTemplateLoaderMixin]{load_template}{name}
Return the parsed template file specified in the \var{name} argument.
The path to the template file is constructed by performing
\code{os.path.join()} on the \var{base_dir} specified in the
constructor and the \var{name} argument.

If there is an error reading the template a
\exception{TemplateLoadError} will be raised.

If the template has been previously loaded it will only be reloaded if
it has been modified since last load.
\end{methoddesc}

\begin{methoddesc}[CachingTemplateLoaderMixin]{load_template_once}{name}
Call the \method{load_template()} method and return the template if it
is either loaded for the first time or reloaded, else return
\code{None}.
\end{methoddesc}

\section{RecorderMixin Classes\label{mixin-recorder}}

This mixin is passed form and input field recording messages as
\texttt{<al-form>}, \texttt{<al-input>}, \texttt{<al-select>}, and
\texttt{<al-a>} tags are executed.  Albatross supplies two classes;
\class{StubRecorderMixin} and \class{NameRecorderMixin}.

\subsection{StubRecorderMixin\label{mixin-rec-stub}}

The \class{StubRecorderMixin} class ignores all form events.

\begin{methoddesc}[StubRecorderMixin]{form_open}{}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubRecorderMixin]{form_close}{}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubRecorderMixin]{input_add}{itype, name \optional{, value \code{= None}}}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubRecorderMixin]{merge_request}{}
Does nothing.
\end{methoddesc}

\subsection{NameRecorderMixin\label{mixin-rec-name}}

The \class{NameRecorderMixin} class writes the names of all input
fields in a form to a hidden field named \texttt{__albform__} at the
end of the form.

When the browser submits a form with this field the application
\method{merge_request()} method calls the \method{merge_request()}
method of this class to merge the browser request into
\code{ctx.locals}.

\begin{methoddesc}[NameRecorderMixin]{__init__}{}
When you inherit from the \class{NameRecorderMixin} class you must
call the constructor.
\end{methoddesc}

\begin{methoddesc}[NameRecorderMixin]{form_open}{}
Called when the \texttt{<al-form>} tag is opened.
\end{methoddesc}

\begin{methoddesc}[NameRecorderMixin]{form_close}{}
Called just before the \texttt{<al-form>} tag is closed.  A hidden
field named \texttt{__albform__} is written to the output.
\end{methoddesc}

\begin{methoddesc}[NameRecorderMixin]{input_add}{itype, name \optional{, value \code{= None}} \optional{, return_list \code{= 0}}}
Called when an \texttt{<al-input>} tag is executed.  The \var{itype}
argument contains the \texttt{type} attribute from the input tag,
\var{name} contains the \texttt{name} tag attribute, and \var{value}
contains the value of the input field if it is known and relevant.
The \var{return_list} argument indicates the presence of the
\texttt{list} attribute on the input tag.

As fields are added to each form the value of the \var{return_list}
argument is checked against any previous setting of the argument for
the same field name.  The argument value is also checked against
whether or not there are multiple instances of the field name.  An
detected discrepancy between the argument value and actual fields will
raise a \exception{FieldTypeError} exception.

Input field types \texttt{radio}, \texttt{image}, and \texttt{submit}
are implicitly flagged to return a list of values.
\end{methoddesc}

\begin{methoddesc}[NameRecorderMixin]{merge_request}{}
Retrieves the \texttt{__albform__} value from the browser request
decodes it and then merges the browser request into the local
namespace accordingly.

If an input field has been flagged to return a list (via the
\texttt{list} tag attribute) then the method will create a list in
\code{ctx.locals} for the field regardless of the number of values
sent by the browser.  An empty list is created when the field is
missing from the browser request.
\end{methoddesc}

\section{NamespaceMixin Class\label{mixin-namespace}}

Albatross only supplies one class for this function; the
\class{NamespaceMixin} class.  This mixin provides a local and global
namespace for evaluating expressions embedded in HTML template files.

When the browser request is merged into the execution context the
input field values are written to the local namespace.

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

The global namespace for evaluating Python expressions in HTML
templates is initialised as an empty dictionary in the constructor.
\end{methoddesc}

\begin{memberdesc}[NamespaceMixin]{locals}
An empty object which is used for the local namespace for evaluating
expressions in HTML templates.  It is initialised as an instance of an
empty class in the constructor to allow values to simply be assigned
to attributes of this member.

Loading the session merges the session values into this member.
\end{memberdesc}

\begin{methoddesc}[NamespaceMixin]{clear_locals}{}
Resets the \member{locals} member to an empty object.
\end{methoddesc}

\begin{methoddesc}[NamespaceMixin]{set_globals}{dict}
Sets the global namespace for evaluating expressions to the \var{dict}
argument.

The \class{SimpleContext} class constructor automatically sets this to
the globals of the function which invoked the \class{SimpleContext}
constructor.

The \method{run_template()} and \method{run_template_once()} methods
of the \class{AppContext} calls this method to set global namespace to
the globals of the calling function.
\end{methoddesc}

\begin{methoddesc}[NamespaceMixin]{eval_expr}{expr}
Called by the template file interpreter to evaluate the embedded
Python expression in the \var{expr} argument.
\end{methoddesc}

\begin{methoddesc}[NamespaceMixin]{set_value}{name, value}
Sets the local namespace attribute named in the \var{name} argument to
the value in the \var{value} argument.  If the \var{name} argument
begins with an underscore the method will raise a
\exception{SecurityError} exception.

This is used by the application \method{merge_request()} method to
merge individual browser request fields into the local namespace.

There is a special ``backdoor'' identifier format which which directs
browser request fields to the \method{set_backdoor()} method of
\class{ListIterator} and \class{TreeIterator} objects.  The backdoor
identifiers are generated by the \texttt{<al-input>} and
\texttt{<al-a>} tags to implement sequence and tree browsing requests.

The method implements a parser which can handle names of the form:

\begin{productionlist}
\production{name}
 {identifier | list-backdoor | tree-backdoor}

\production{identifier}
 {identifier (("." identifier) | ("[" number "]"))*}

\production{list-backdoor}
 {operation "," iter}

\production{tree-backdoor}
 {operation "," iter "," alias}
\end{productionlist}
\end{methoddesc}

\begin{methoddesc}[NamespaceMixin]{make_alias}{name}
Called to generate an alternate name for an object referenced in the
\texttt{alias} attribute of an Albatross tag.

The method resolves the \var{name} argument up to the last ``.'' and
then calls the \method{albatross_alias()} method of the resolved
object.  The resolved object is then entered into the local namespace
and the session using the name returned by \method{albatross_alias()}.

The return value is a new name by combining the name returned by
\method{albatross_alias()} with the part of the original name
following and including the last ``.''.

Refer to the \texttt{<al-input>} documentation on page
\pageref{tag-input} in section \ref{tag-input} for an explanation of
why this method exists.
\end{methoddesc}

\begin{methoddesc}[NamespaceMixin]{get_value}{name}
Retrieves the value identified by the \var{name} argument from the
local namespace.  If the named value does not exist then \code{None}
is returned.
\end{methoddesc}

\begin{methoddesc}[NamespaceMixin]{has_value}{name}
Returns whether or not the value named in the \var{name} attribute
exists in the local namespace.
\end{methoddesc}

\begin{methoddesc}[NamespaceMixin]{has_values}{\ldots}
Returns TRUE only if values named in the argument list exist in the
local namespace.
\end{methoddesc}

\section{SessionContextMixin Classes\label{mixin-ctxsession}}

This mixin is used to manage the encoding and decoding of session
data.  Albatross supplies a number of classes for use in the execution
context; \class{StubSessionMixin}, \class{SessionBase},
\class{HiddenFieldSessionMixin}, \class{SessionServerContextMixin},
and \class{SessionFileContextMixin}.  The \class{SessionBase} class
provides base functionality for non-stub session classes.

Loading and storing of session data is usually performed by an
application mixin.

The \class{SessionServerAppMixin} is designed to be used in the
application object.

\subsection{StubSessionMixin\label{mixin-ses-stub}}

The \class{StubSessionMixin} class ignores all session operations.

\begin{methoddesc}[StubSessionMixin]{add_session_vars}{\ldots}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubSessionMixin]{del_session_vars}{\ldots}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubSessionMixin]{encode_session}{}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubSessionMixin]{load_session}{}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubSessionMixin]{save_session}{}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubSessionMixin]{remove_session}{}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubSessionMixin]{set_save_session}{flag}
Does nothing.
\end{methoddesc}

\begin{methoddesc}[StubSessionMixin]{should_save_session}{}
Returns \code{0}.
\end{methoddesc}

\subsection{SessionBase\label{mixin-ses-base}}

The \class{SessionBase} class provides base session handling
functionality which is used by all standard Albatross execution
context session mixin classes.

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

The class maintains a dictionary of all names from the execution
context local namespace which belong in the session.  This dictionary
is restored along with the session when the session is decoded.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{add_session_vars}{\ldots}
Adds all listed names to the session dictionary.  The named variables
must exist in the \member{locals} member or a \exception{SessionError}
will be raised.

The names can optionally be supplied as a list or tuple of names.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{default_session_var}{name, value}
Adds a name to the session directory. Sets a value in the local namespace
if the name is not already in the local namespace.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{del_session_vars}{\ldots}
Deletes all listed names from the session dictionary.

The names can optionally be supplied as a list or tuple of names.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{session_vars}{}
Returns a list of the names that are currently in the session.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{remove_session}{}
Deletes all names from the session dictionary and clears all values
from the local namespace via the \method{clear_locals()} method.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{decode_session}{text}
Performs \code{cPickle.loads()} to retrieve a dictionary of session
values.  The dictionary is merged into the session local namespace.
Adds the keys of the dictionary to the session dictionary.

Just before calling \code{cPickle.loads()} the method inserts (and
after removes) the application page module directory into
\code{sys.path}.  This allows the pickler to find classes which are
defined in application page modules.  The page module directory is
determined by calling the \method{app.module_path()} method.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{encode_session}{}
Builds a dictionary by extracting all local namespace values which are
listed in the session dictionary.  A test pickle is performed on each
value and any unpickleable value is discarded and an error message is
written to \code{sys.stderr}.

The dictionary is then passed to \code{cPickle.dumps()} and the result
is returned.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{set_save_session}{flag}
Sets the flag which controls whether the session will be saved at the
end of request processing.  By default the internal flag is
\code{TRUE} which means the session will be saved.
\end{methoddesc}

\begin{methoddesc}[SessionBase]{should_save_session}{}
Returns the flag which controls whether the session will be saved at
the end of request processing.
\end{methoddesc}

\subsection{HiddenFieldSessionMixin\label{mixin-ses-field}}

Saves session state to a hidden field named \texttt{__albstate__} at
the end of every form produced by \texttt{<al-form>} tags.

Inherits from the \class{SessionBase} class so you must call the
constructor if you subclass this class.

\begin{methoddesc}[HiddenFieldSessionMixin]{encode_session}{}
Extends the base class \method{encode_session()} method to
\code{zlib.compress()} and \code{base64.encodestring()} the result.
This makes the session data suitable for placing in a hidden field in
the HTML.
\end{methoddesc}

\begin{methoddesc}[HiddenFieldSessionMixin]{load_session}{}
This is called from the \class{Application} class
\method{load_session()} method.  The session state is retrieved from
the browser request, decoded and decompressed then passed to the
\method{decode_session()} method.
\end{methoddesc}

\begin{methoddesc}[HiddenFieldSessionMixin]{save_session}{}
This is called from the \class{Application} class
\method{save_session()} method at the end of the request processing
sequence.  The method does nothing because the session state is saved
in hidden fields in the HTML.
\end{methoddesc}

\begin{methoddesc}[HiddenFieldSessionMixin]{form_close}{}
Called just before the \texttt{<al-form>} tag is closed.  If the
session is flagged to be saved a hidden field named
\texttt{__albstate__} is written to the output.

Note that this method is also present in the \class{RecorderMixin}, so
if you inherit from the \class{HiddenFieldSessionMixin} class you must
define a \method{form_close()} method in the derived class which calls
this method in both of the super classes.
\end{methoddesc}

\subsection{SessionServerContextMixin\label{mixin-ctx-sess}}

This class works in concert with the \class{SessionServerAppMixin}
application mixin class to store session data in the Albatross session
server.  All management of session data storage is performed by the
application class.

Inherits from the \class{SessionBase} class so you must call the
constructor if you subclass this class.

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

\begin{methoddesc}[SessionServerContextMixin]{sesid}{}
Returns the session id.
\end{methoddesc}

\begin{methoddesc}[SessionServerContextMixin]{load_session}{}
This is usually called from the \class{Application} class
\method{load_session()} method.  Retrieves the session id and then
either retrieves an existing session or creates a new session via the
application object.

If an existing session is retrieved it is passed to
\code{base64.decodestring()} and \code{zlib.decompress()} then passed
to the \method{decode_session()} method (inherited from the
superclass).  If an exception is raised during
\method{decode_session()} then the session will be deleted from the
server and a new session will be created via the application object
\method{new_session()} method.
\end{methoddesc}

\begin{methoddesc}[SessionServerContextMixin]{save_session}{}
This is called from the \class{Application} class
\method{save_session()} method at the end of the request processing
sequence.  If the session save flag has been cleared via the
\method{set_save_session()} method then the session is not saved.

Before saving a session the method calls the superclass
\method{encode_session()} then calls \code{zlib.compress()} and
\code{base64.encodestring()} to convert the session to plain text
which is passed to the \method{put_session()} application method to
save the session.
\end{methoddesc}

\begin{methoddesc}[SessionServerContextMixin]{remove_session}{}
This is called from the \class{Application} class
\method{remove_session()} method.  The method calls the superclass
\method{remove_session()} then calls the \method{del_session()}
application method to remove the session at the server.
\end{methoddesc}

\subsection{SessionFileContextMixin\label{mixin-ctx-file-sess}}

This class works in concert with the \class{SessionFileAppMixin}
application mixin class to store session data in the local file-system.
All management of session data storage is performed by the application
class.

Inherits from the \class{SessionBase} class so you must call the
constructor if you subclass this class.

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

\begin{methoddesc}[SessionFileContextMixin]{sesid}{}
Returns the session id.
\end{methoddesc}

\begin{methoddesc}[SessionFileContextMixin]{load_session}{}
This is usually called from the \class{Application} class
\method{load_session()} method.  Retrieves the session id and then
either retrieves an existing session or creates a new session via the
application object.

If an existing session is retrieved it is passed to the
\method{decode_session()} method (inherited from the
superclass).  If an exception is raised during
\method{decode_session()} then the session will be deleted from the
server and a new session will be created via the application object
\method{new_session()} method.
\end{methoddesc}

\begin{methoddesc}[SessionFileContextMixin]{save_session}{}
This is called from the \class{Application} class
\method{save_session()} method at the end of the request processing
sequence.  If the session save flag has been cleared via the
\method{set_save_session()} method then the session is not saved.

Before saving a session the method calls the superclass
\method{encode_session()} then calls the \method{put_session()}
application method to save the session.
\end{methoddesc}

\begin{methoddesc}[SessionFileContextMixin]{remove_session}{}
This is called from the \class{Application} class
\method{remove_session()} method.  The method calls the superclass
\method{remove_session()} then calls the \method{del_session()}
application method to remove the session at the server.
\end{methoddesc}

\section{SessionAppMixin Classes\label{mixin-appsession}}

\subsection{SessionServerAppMixin\label{mixin-app-sess}}

The application mixin works in concert with the
\class{SessionServerContextMixin} execution context method to store
sessions in the Albatross session server.

Whenever there are problems communicating with the session server
the class raises a \exception{SessionServerError} exception,
which is a subclass of \exception{SessionError}. Unless you have a
reason to do otherwise, catch \exception{SessionError} rather than
\exception{SessionServerError}, as this allows other Session classes to
be substituted with minimal change.

\begin{methoddesc}[SessionServerAppMixin]{__init__}{appid \optional{, server \code{= 'localhost'}} \optional{, port \code{= 34343}} \optional{, age \code{= 1800}}}
When you inherit from the \class{SessionServerAppMixin} class you must
call this constructor.

The \var{appid} argument specifies the name of the cookie attribute
which is used to store the session id.  This uniquely identifies the
application at the web server.  Multiple applications can share
sessions by defining the same value in this argument.

The \var{server} and \var{port} arguments specify the location of the
Albatross session server.  By using a session server you can have a
number of web serving machines which transparently share session data.

The \var{age} argument specifies how long (in seconds) an idle session
will be stored at the server before it is discarded.

A connection to the session server is established.  The connection
will be kept open for the lifetime of the application object.
\end{methoddesc}

\begin{methoddesc}[SessionServerAppMixin]{ses_appid}{}
Returns the \var{appid} argument which was passed to the constructor.
\end{methoddesc}

\begin{methoddesc}[SessionServerAppMixin]{get_session}{sesid}
Returns the session identified by \var{sesid} argument and the
\var{appid} passed to the constructor.  If no such session exists
\code{None} is returned.
\end{methoddesc}

\begin{methoddesc}[SessionServerAppMixin]{new_session}{}
Returns a new session id for the \var{appid} passed to the constructor.
\end{methoddesc}

\begin{methoddesc}[SessionServerAppMixin]{put_session}{sesid, text}
Saves the \var{text} argument as session data for the session
identified by \var{sesid} argument and the \var{appid} passed to the
constructor.
\end{methoddesc}

\begin{methoddesc}[SessionServerAppMixin]{del_session}{sesid}
Removes the session identified by \var{sesid} argument and the
\var{appid} passed to the constructor.
\end{methoddesc}

\subsection{SessionFileAppMixin\label{mixin-app-file-sess}}

The application mixin works in concert with the
\class{SessionFileContextMixin} execution context method to store
sessions in the local file-system.

Whenever there are problems reading or writing sessions from or to
disk, the class raises a \exception{SessionFileError} exception,
which is a subclass of \exception{SessionError}. Unless you have a
reason to do otherwise, catch \exception{SessionError} rather than
\exception{SessionFileError}, as this allows other Session classes to
be substituted with minimal change.

\begin{methoddesc}[SessionFileAppMixin]{__init__}{appid , session_dir}
When you inherit from the \class{SessionFileAppMixin} class you must
call this constructor.

The \var{appid} argument specifies the name of the cookie attribute
which is used to store the session id.  This uniquely identifies the
application at the web server.  Multiple applications can share
sessions by defining the same value in this argument.

The \var{session_dir} argument specifies the location on the local
file-system in which this application's sessions will be stored.

The directory should not be publicly readable, as the session file names
are the session id's (knowing a session id allows an attacker to steal
that session).

Sessions recorded via this class are not automatically aged. An external
process will be required to clean orphaned sessions from the session
directory (for example, by removing any file that has not been accessed
in the last two hours).
\end{methoddesc}

\begin{methoddesc}[SessionFileAppMixin]{ses_appid}{}
Returns the \var{appid} argument which was passed to the constructor.
\end{methoddesc}

\begin{methoddesc}[SessionFileAppMixin]{get_session}{sesid}
Returns the session identified by \var{sesid} argument and the
\var{appid} passed to the constructor.  If no such session exists
\code{None} is returned.
\end{methoddesc}

\begin{methoddesc}[SessionFileAppMixin]{new_session}{}
Returns a new session id for the \var{appid} passed to the constructor.

Note that if the \var{session_dir} passed to the constructor does not
already exist, this method will attempt to create it.
\end{methoddesc}

\begin{methoddesc}[SessionFileAppMixin]{put_session}{sesid, text}
Saves the \var{text} argument as session data for the session
identified by \var{sesid} argument and the \var{appid} passed to the
constructor.
\end{methoddesc}

\begin{methoddesc}[SessionFileAppMixin]{del_session}{sesid}
Removes the session identified by \var{sesid} argument and the
\var{appid} passed to the constructor.
\end{methoddesc}

\section{PickleSignMixin Classes\label{mixin-sign}}

This is mixed with the application class to sign or modify pickles
before sending them to the browser and to undo and check that
modification on the return trip.  When processing modified pickles
returned from the browser the class discards pickles which do not pass
the security check.

There is only one mixin supplied for this function; the
\class{PickleSignMixin} class.  Pickle strings are combined with the
secret string which was passed to the application constructor as the
\var{secret} argument.  The MD5 sign for the combined string is then
prepended to the pickle.  On the return trip the MD5 sign is removed
compared with the result of the signing process on the pickle returned
from the browser.  If the two signs are not the same, the pickle is
discarded.

The process does not prevent users from seeing the contents of a
pickle.  Assuming that you keep your secret, to modify the pickle a
user must be able to crack the 128 bit MD5 sign.

The mixin has the following interface.

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

The \var{secret} argument is the secret which is used to protect the
MD5 sign.
\end{methoddesc}

\begin{methoddesc}[PickleSignMixin]{pickle_sign}{text}
Generates an MD5 sign for the \var{secret} constructor argument and
pickle string passed in the \var{text} argument.  The return string
prepends the 16 byte MD5 sign to the string passed in the \var{text}
argument.
\end{methoddesc}

\begin{methoddesc}[PickleSignMixin]{pickle_unsign}{text}
Removes the 16 byte MD5 sign prefix and the resigns the remaining
string.  If the two signs match the unprefixed string is returned.  If
the signs do not match the method returns an empty string.
\end{methoddesc}

\section{PageMixin Classes\label{mixin-page}}

The choice of mixin for this functionality determines how Albatross
will locate the code to process the browser request and display the
response for each page.  Albatross supplies three classes;
\class{PageModuleMixin}, \class{RandomPageModuleMixin}, and
\class{PageObjectMixin}.

\subsection{PageModuleMixin\label{mixin-page-module}}

This class uses a separate Python module for each page in the
application.  This scales very well at runtime because at most two
modules will be loaded for each request; one to process the browser
request, and possibly another to display the response.  Page modules
are cached for further efficiency.  The class is designed to be used
where the application controls the sequence of pages seen in a browser
session so the start page is also specified in the constructor.

Application page modules are loaded from a root directory which is
specified in the constructor.  The current application page is
identified by the path to the page module relative to the module root
directory.  Page identifiers consist of an optional path component
followed by a module name without extension.  For example
\texttt{"login"}, \texttt{"user/list"}, \texttt{"home-page/default"}.

To load a page module the class combines the root directory passed to
the constructor with the page identifier using \code{os.path.join()}.
It then checks the page module cache to see if the module needs to be
imported or reloaded.  If the module needs to be imported, the full
module path is split into directory and filename components using
\code{os.path.split()}.  The standard module importer in the
\module{imp} module is then used load the page module using the
filename part of the full path as the module name and the directory
component as the module search path.  The simplified code looks like
this:

\begin{verbatim}
path = os.path.join(self.module_base_dir, name)
dirname, name = os.path.split(path)
file, filepath, desc = imp.find_module(name, [dirname])
page = imp.load_module(name, file, filepath, desc)
\end{verbatim}

Due to this load method page module identifiers are not relative to
the current page, they are always relative to the module root
directory specified in the \var{base_dir} argument to the
\class{PageModuleMixin} constructor.

Page modules handled by this mixin have the following interface:

\begin{funcdescni}{page_enter}{ctx \optional{, \ldots}}
If this function is present in the new page module it will be called
whenever your application code calls the execution context
\method{set_page()} method.  For application types which define a
start page this method is called in the start page when a new session
is created.

The \var{ctx} argument contains the execution context.  Any extra
arguments which are passed to the \function{set_page()} method are
passed as optional extra arguments to this function.
\end{funcdescni}

\begin{funcdescni}{page_leave}{ctx}
If this function is present in the current page module it will be
called whenever your application code changes to another page by
calling the execution context \method{set_page()} method.

The \var{ctx} argument contains the execution context.
\end{funcdescni}

\begin{funcdescni}{page_process}{ctx}
If this function is present in the page module it will be called when
the application object executes the \method{process_request()} method.
This occurs if the browser request was successfully validated.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{funcdescni}

\begin{funcdescni}{page_display}{ctx}
This is the only mandatory page module function.  The application
object calls this function when it executes the
\method{display_response()} method as the final step before saving the
browser session.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{funcdescni}

The \class{PageModuleMixin} class has the following interface.

\begin{methoddesc}[PageModuleMixin]{__init__}{base_dir, start_page}
When you inherit from the \class{PageModuleMixin} class you must call
this constructor.

The \var{base_dir} argument specifies the path of the root directory
where page modules are loaded from.  When deploying your application
as a CGI program you can specify a relative path from the location of
the application mainline.  Apache sets the current directory to root
so when using \texttt{mod_python} deployment you will need to specify
a path relative to the root.

The \var{start_page} argument is a page identifier which specifies
the first page that new browser session will see.
\end{methoddesc}

\begin{methoddesc}[PageModuleMixin]{module_path}{}
Returns the \var{base_dir} which was passed to the constructor.
\end{methoddesc}

\begin{methoddesc}[PageModuleMixin]{start_page}{}
Returns the \var{start_page} which was passed to the constructor.
\end{methoddesc}

\begin{methoddesc}[PageModuleMixin]{load_page}{ctx}
This method implements part of the standard application processing
sequence.  It is called immediately after restoring the browser
session.  The \var{ctx} argument is the execution context for the
current browser request.

If no current page is defined in \var{ctx} then the method will invoke
\method{ctx.set_page()} passing the page specified as the
\var{start_page} argument to the application constructor.

The actual page module load is performed via the
\method{load_page_module()} method.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\begin{methoddesc}[PageModuleMixin]{load_page_module}{ctx, name}
Loads the page module identified by the \var{name} argument and saves
a reference to the module in the \member{page} member.
\end{methoddesc}

\begin{methoddesc}[PageModuleMixin]{page_enter}{ctx, args}
Called when your application code calls the execution context
\method{set_page()} method.  The \var{ctx} argument is the execution
context for the current browser request.  The \var{args} argument is a
tuple which contains all optional extra arguments which were passed to
the \method{set_page()} method.

The page module \function{page_enter()} function is called by this
method.
\end{methoddesc}

\begin{methoddesc}[PageModuleMixin]{page_leave}{ctx}
Called before changing pages when your application code calls the
execution context \method{set_page()} method.  The \var{ctx} argument
is the execution context for the current browser request.

The page module \function{page_leave()} function is called by this
method.
\end{methoddesc}

\begin{methoddesc}[PageModuleMixin]{process_request}{ctx}
This method implements part of the standard application processing
sequence.  It is called if the browser request is successfully
validated.  The \var{ctx} argument is the execution context for the
current browser request.

The page module \function{page_process()} function is called by this
method.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\begin{methoddesc}[PageModuleMixin]{display_response}{ctx}
This method implements part of the standard application processing
sequence.  It is called as the final stage just before the session is
saved.  The \var{ctx} argument is the execution context for the
current browser request.

The page module \function{page_display()} function is called by this
method.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\subsection{RandomPageModuleMixin\label{mixin-randpage-module}}

This class inherits from the \class{PageModuleMixin} class.  It
redefines the way in which page modules are selected.

Instead of the application calling the \method{set_page()} execution
context method, the URL in the browser request controls which page
module is loaded and processed for each request.

Page module management is inherited from \class{PageModuleMixin}.  The
\var{base_dir} argument to the constructor determines the root
directory where modules are loaded from.

Page modules handled by this mixin have the following interface:

\begin{funcdescni}{page_enter}{ctx}
If this function is present in the page module it will be called
every time the page module is used for a browser request.

The \var{ctx} argument contains the execution context.
\end{funcdescni}

\begin{funcdescni}{page_process}{ctx}
If this function is present in the page module it will be called when
the application object executes the \method{process_request()} method.
This occurs if the browser request was successfully validated.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{funcdescni}

\begin{funcdescni}{page_display}{ctx}
This is the only mandatory page module function.  The application
object calls this function when it executes the
\method{display_response()} method as the final step before saving the
browser session.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{funcdescni}

The \class{RandomPageModuleMixin} class has the following interface.

\begin{methoddesc}[RandomPageModuleMixin]{load_page}{ctx}
This method implements part of the standard application processing
sequence.  It is called immediately after restoring the browser
session.  The \var{ctx} argument is the execution context for the
current browser request.

The \method{get_page_from_uri()} method is called to determine the
identifier of the page module that will be loaded.  The identifier is
then passed to the \method{load_page_module()} method (which is
inherited from \class{PageModuleMixin}).

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\begin{methoddesc}[RandomPageModuleMixin]{get_page_from_uri}{ctx, uri}
The method uses the \function{urlparse()} function from the standard
Python \function{urlparse} module to extract the path component from
both the \var{uri} parameter and the value returned by the
\method{base_url()} method (which returns the \var{base_url} argument
to the application constructor).

The \var{path} component of the \var{base_url} is then used to split
the \var{path} component of the \var{uri}.  Element one (first split
to the right of \var{base_url}) of the resulting string list is
returned as the page identifier.

Override this method in your application if you wish to implement a
your own scheme for mapping the request onto a page identifier.
\end{methoddesc}

\begin{methoddesc}[RandomPageModuleMixin]{load_badurl_template}{ctx}
Called when your page template identified by the request URL does not
exist.  The \var{ctx} argument is the execution context for the
current browser request.

Override this method if you want to supply a different error page
template.
\end{methoddesc}

\begin{methoddesc}[RandomPageModuleMixin]{page_enter}{ctx}
Called as soon as the page module has been loaded.  The \var{ctx}
argument is the execution context for the current browser request.

The page module \function{page_enter()} function is called by this
method if a page module was located by the \method{load_page()}
method.
\end{methoddesc}

\begin{methoddesc}[RandomPageModuleMixin]{process_request}{ctx}
This method implements part of the standard application processing
sequence.  It is called if the browser request is successfully
validated.  The \var{ctx} argument is the execution context for the
current browser request.

The page module \function{page_process()} function is called by this
method if a page module was located by the \method{load_page()}
method.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\begin{methoddesc}[RandomPageModuleMixin]{display_response}{ctx}
This method implements part of the standard application processing
sequence.  It is called as the final stage just before the session is
saved.  The \var{ctx} argument is the execution context for the
current browser request.

The page module \function{page_display()} function is called by this
method if a page module was located by the \method{load_page()}
method.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\subsection{PageObjectMixin\label{mixin-page-object}}

This class is intended for applications which do not require a
separate Python module for each page in the application.  Page
processing is performed by a set of objects which the application
registers with this class.  The class is designed to be used where the
application controls the sequence of pages seen in a browser session
so the start page is specified in the constructor.

Application page objects must be registered before they can be used.
Typically you will register the page objects immediately after
constructing your application object.  Since the current application
page is identified by an internal value, any hashable pickleable value
can be used as an identifier.

Page objects handled by this mixin have the following interface:

\begin{methoddescni}[PageObject]{page_enter}{ctx \optional{, \ldots}}
If this method is present in the new page object it will be called
whenever your application code changes current the page by calling the
execution context \method{set_page()} method.  For application types
which define a start page this method is called in the start page when
a new session is created.

The \var{ctx} argument contains the execution context.  Any extra
arguments which are passed to the \function{set_page()} method are
passed as optional extra arguments to this method.
\end{methoddescni}

\begin{methoddescni}[PageObject]{page_leave}{ctx \optional{, \ldots}}
If this method is present in the old page object it will be called
whenever your application code changes current the page by calling the
execution context \method{set_page()} method.

The \var{ctx} argument contains the execution context.
\end{methoddescni}

\begin{methoddescni}[PageObject]{page_process}{ctx}
If this method is present in the page object it will be called when
the application object executes the \method{process_request()} method.
This occurs if the browser request was successfully validated.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddescni}

\begin{methoddescni}[PageObject]{page_display}{ctx}
This is the only mandatory page object function.  The application
object calls this method when it executes the
\method{display_response()} method as the final step before saving the
browser session.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddescni}

The \class{PageObjectMixin} class has the following interface.

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

The \var{start_page} argument is a page identifier which specifies
the first page that new browser session will see.
\end{methoddesc}

\begin{methoddesc}[PageObjectMixin]{module_path}{}
Returns \code{None}.
\end{methoddesc}

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

\begin{methoddesc}[PageObjectMixin]{register_page}{name, obj}
You must call this method to register every page object in your
application.  The \var{name} argument defines the page identifier
which is used to select the page object specified in the \var{obj}
argument.  All pages must be registered before they can be used.
\end{methoddesc}

\begin{methoddesc}[PageObjectMixin]{load_page}{ctx}
This method implements part of the standard application processing
sequence.  It is called immediately after restoring the browser
session.  The \var{ctx} argument is the execution context for the
current browser request.

If no current page is defined in \var{ctx} then the method will invoke
\method{ctx.set_page()} passing the page specified as the
\var{start_page} argument to the application constructor.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\begin{methoddesc}[PageObjectMixin]{page_enter}{ctx, args}
Called when your application code calls the execution context
\method{set_page()} method.  The \var{ctx} argument is the execution
context for the current browser request.  The \var{args} argument is a
tuple which contains all optional extra arguments which were passed to
the \method{set_page()} method.

The page object \function{page_enter()} method is called by this
method.
\end{methoddesc}

\begin{methoddesc}[PageObjectMixin]{page_leave}{ctx}
Called before changing pages when your application code calls the
execution context \method{set_page()} method.  The \var{ctx} argument
is the execution context for the current browser request.

The page object \function{page_leave()} method is called by this
method.
\end{methoddesc}

\begin{methoddesc}[PageObjectMixin]{process_request}{ctx}
This method implements part of the standard application processing
sequence.  It is called if the browser request is successfully
validated.  The \var{ctx} argument is the execution context for the
current browser request.

The page object \function{page_process()} method is called by this
method.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\begin{methoddesc}[PageObjectMixin]{display_response}{ctx}
This method implements part of the standard application processing
sequence.  It is called as the final stage just before the session is
saved.  The \var{ctx} argument is the execution context for the
current browser request.

The page object \function{page_display()} method is called by this
method.

Refer to page \pageref{app-proc-seq} in section \ref{app-proc-seq} for
an overview of the application processing sequence.
\end{methoddesc}

\section{Request Classes\label{mixin-request}}

The choice of \class{Request} class determines how you wish to deploy
your application.  Albatross currently supplies two classes;
\class{cgiapp.Request} for CGI deployment and
\class{apacheapp.Request} for deployment using \texttt{mod_python}.

By placing all deployment dependencies in a \class{Request} class you
are able to change deployment method with only minimal changes to your
application mainline code.  This is useful for development as a CGI
application and final deployment inside Apache.

In theory you could develop your own \class{Request} class to deploy
an Albatross application using the Medusa web server.

Future versions of Albatross will provide a \class{Request} class
which for performing unit tests on your application.

All \class{Request} classes implement the same interface.

\begin{methoddesc}[Request]{has_field}{name}
Returns \code{TRUE} if the field identified by the \var{name} argument
is present in the request.
\end{methoddesc}

\begin{methoddesc}[Request]{field_value}{name}
Return the value of the field identified by the \var{name} argument.
\end{methoddesc}

\begin{methoddesc}[Request]{field_file}{name}
Returns an object that contains the value of a file input field.
\end{methoddesc}

\begin{methoddesc}[Request]{field_names}{}
Return a list of all all fields names in the request.
\end{methoddesc}

\begin{methoddesc}[Request]{get_uri}{}
Return the URL which the browser used to perform the request.
\end{methoddesc}

\begin{methoddesc}[Request]{get_servername}{}
Return the name of the server (Apache ServerName setting).
\end{methoddesc}

\begin{methoddesc}[Request]{get_header}{name}
Return the value of the HTTP header identified in the \var{name}
argument.
\end{methoddesc}

\begin{methoddesc}[Request]{write_header}{name, value}
Set the header named in the \var{name} argument to the \var{value}
argument.  Once you have started sending content to the browser the
method will not do anything.
\end{methoddesc}

\begin{methoddesc}[Request]{end_headers}{}
Send all accumulated headers and start sending content.  This method
will be automatically called when you start sending content to the
browser via \method{write_content()}.
\end{methoddesc}

\begin{methoddesc}[Request]{redirect}{loc}
Send a \texttt{"301 Moved Permanently"} response back to the browser.
\end{methoddesc}

\begin{methoddesc}[Request]{write_content}{data}
Send \var{data} as part of the request response.
\end{methoddesc}

\begin{methoddesc}[Request]{set_status}{status}
Sets the status that will be returned from the \class{Application}
class \method{run()} method.
\end{methoddesc}

\begin{methoddesc}[Request]{status}{num}
Return a value for the HTTP status code in the \var{num} argument
which is suitable for returning as the result of the application
\method{run()} method.

For example, the \texttt{mod_python} deployment typically uses this
method in a roundabout way like this:

\begin{verbatim}
from albatross.apacheapp import Request
  :
  :
def handler(req):
    return app.run(Request(req))
\end{verbatim}
\end{methoddesc}
