.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. % Copyright 2001 by Object Craft P/L, Melbourne, Australia.
.. % LICENCE - see LICENCE file distributed with this software for details.
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


.. _pack-overview:

*****************************************************
Prepackaged Application and Execution Context Classes
*****************************************************

While Albatross invites you to "roll your own", in most cases you will
use one of the prepackaged Application and Context classes. There are two
primary choices to be made when selecting an Application class: the **page
model** and the **context model**. The page model offers three choices:

* **simple**
 
  The simple model is intended for use in monolithic applications. Page
  logic is represented by classes.

* **modular**

  The modular model defines page logic in a collection of Python models,
  one per page.

* **random**

  The random model extends the modular model, however the current page
  module is selected via the URI in the browser request.

There are four context models:

* **hidden-field**

  The hidden-field model stores session state in the user's browser in
  hidden HTML fields.

* **session-server**

  The session-server model stores session state on the server using a
  separate session server process. An HTTP cookie is used to match a user
  session to their state on the server.

* **session-file**

  Similar to the session-server model, the session-file model stores session
  state on the server. However, rather than requiring a session server
  daemon, this model stores the state in files on the server.  This can
  be simpler to set up, but all server processes must run on the one machine.

* **branching-server**

  The branching-server model stores session state on the server in the same
  way as the session-server model, but uses hidden HTML fields to track users,
  and retains multiple versions of the state. This provides more flexibility
  when supporting users who use the browser "back" button or who duplicate
  their sessions, at the cost of more server-side storage.

There are 12 combinations of page and context model, although not all
combinations are supported :- it is not possible to combine the `random`
page model with the `hidden-field` or `branching-server` context models
as these context models require a hidden form field to be sent via the
client to maintain state, and this does not always happen with random
access applications.

Choosing the appropriate class is made easier by the
``get_app_classes(page_model, context_model)`` function. Given the names
of a page model and context model, this returns a 2-tuple containing a
pre-packaged Application class and a matching Context class. These can be
instantiated directly, or subclassed to add further functionality:

  .. code-block:: python

    import albatross

    appcls, ctxcls = albatross.get_app_classes('simple', 'hidden-field')

    class Context(ctxcls):

        def __init__(self, app):
            ctxcls.__init__(self, app)
        
    class Application(appcls):

        def create_context(self):
            return Context(self)

    app = Application()


.. figure:: .build/figures/AlbatrossObjects.*
   :align: center

   Albatross Classes


.. _pack-simplecontext:

The ``SimpleContext`` Execution Context
=======================================

The ``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 ``SimpleContext`` class looks like this:

.. _fig-simplecontext:

.. figure:: .build/figures/simplecontext.*
   :align: center

   The :class:`SimpleContext` class

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.


   :class:`NamespaceMixin` This mixin provides a local namespace for evaluating the
   expressions embedded in the ``expr`` tag attributes.  Application code places
   values into the :attr:`locals` member to make them available for display by the
   template files.

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


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


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


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


   :class:`StubRecorderMixin` Albatross provides special versions of the standard
   HTML ``<input>``, ``<select>``, and ``<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.


   :class:`StubSessionMixin`

   Albatross provides an application session.  Applications which do not a session
   can use this mixin to disable session functionality.

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.


.. include:: .build/method-docs/SimpleContext-methods.rst

Looking inside the :mod:`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
:mod:`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.


.. _pack-appcontext:

The ``AppContext`` Base Class
=============================

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.

.. _fig-appcontext:

.. figure:: .build/figures/appcontext.*
   :align: center

   The :class:`AppContext` class

The methods available in :class:`AppContext` and the location of their
definition are show below.


.. include:: .build/method-docs/AppContext-methods.rst

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


.. method:: AppContext.__init__(app)

   When you inherit from the :class:`AppContext` class you must call this
   constructor.

   The *app* argument specifies the application object.  This is saved in the
   :attr:`app` member.


.. attribute:: AppContext.app

   Stores the *app* argument to the constructor.


.. method:: AppContext.get_macro(name)

   Returns the result of the :meth:`get_macro` method of the application in the
   :attr:`app` member.


.. method:: AppContext.register_macro(name, macro)

   Returns the result of the :meth:`register_macro` method of the application in
   the :attr:`app` member.


.. method:: AppContext.get_lookup(name)

   Returns the result of the :meth:`get_lookup` method of the application in the
   :attr:`app` member.


.. method:: AppContext.register_lookup(name, lookup)

   Returns the result of the :meth:`register_lookup` method of the application in
   the :attr:`app` member.


.. method:: AppContext.get_tagclass(name)

   Returns the result of the :meth:`get_tagclass` method of the application in the
   :attr:`app` member.


.. method:: AppContext.load_template(name)

   Returns the result of the :meth:`load_template` method of the application in the
   :attr:`app` member.


.. method:: AppContext.load_template_once(name)

   Returns the result of the :meth:`load_template_once` method of the application
   in the :attr:`app` member.


.. method:: AppContext.run_template(name)

   Calls the application :meth:`load_template` method to load the template
   specified in the *name* argument and sets the execution context global namespace
   to the globals of the function which called this method.  The template
   :meth:`to_html` method is then called to execute the template.


.. method:: AppContext.run_template_once(name)

   Calls the application :meth:`load_template_once` method.  If the template
   specified in the *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 :meth:`to_html` method is then called to execute
   the template.


.. method:: AppContext.clear_locals()

   Overrides the :class:`NamespaceMixin` :meth:`clear_locals` method to retain the
   :attr:`__page__` local namespace value.


.. method:: AppContext.set_page(name [, ...])

   Sets the current application page to that specified in the *name* argument.  If
   changing pages and there is a current page defined then before changing pages
   the :func:`page_leave` function/method will be called for the current page.  The
   :attr:`locals.__page__` member is then set to *name* and the new page is loaded.
   Any addition arguments passed to the method will be passed to the
   :func:`page_enter` function/method code which is associated with the new page.

   Refer to :ref:`mixin-page` for an explanation of page functions/methods.


.. method:: AppContext.push_page(name [, ...])

   Pushes an application page onto the page stack. The current page can be returned
   to by calling the :meth:`pop_page` method. The :func:`page_leave`
   function/method of the current page is not called. The new page is loaded and
   it's :func:`page_enter` function/method is called. Any additional arguments
   given will be passed to the :func:`page_enter` function/method associated with
   the new page.


.. method:: AppContext.pop_page()

   Pops the current page from the page stack and returns to the page that was
   current when the :meth:`push_page` method was called. The :func:`page_leave`
   function/method of the current page is called prior to loading the original
   page. The :func:`page_enter` function/method of the original page is not called.


.. method:: AppContext.set_request(req)

   Saves the browser request specified in the *req* argument as the
   :attr:`request`.


.. method:: AppContext.req_equals(name)

   Returns whether or not the browser request contains a non-empty field with a
   name which matches the *name* argument.


.. method:: AppContext.base_url()

   Returns the result of the application :meth:`base_url` method.


.. method:: AppContext.current_url()

   Returns the path component (see the standard :mod:`urlparse` module) of the URI
   used to request the current page.


.. method:: AppContext.absolute_base_url()

   Returns the *base_url* parameter to the application constructor transformed into
   an absolute URL.


.. method:: AppContext.redirect_url(loc)

   Returns an absolute URL for the application page identifier specified in the
   *loc* parameter.


.. method:: AppContext.redirect(loc)

   Raises a :exc:`Redirect` exception requesting a redirect to the location in the
   *loc* parameter from the application :meth:`run` method.

   If the *loc* parameter contains either a scheme or netloc (from the standard
   :mod:`urlparse` module), or begins with a "/" then is it used without
   modification for the :exc:`Redirect` exception. Other forms of *loc* are assumed
   to be page identifiers and are passed to :meth:`redirect_url` before being
   raised as a :exc:`Redirect` exception.


.. _pack-contextclasses:

Context classes:
================


.. _pack-simpleappcontext:

The ``SimpleAppContext`` Class
------------------------------

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.

.. _fig-simpleappcontext:

.. figure:: .build/figures/simpleappcontext.*
   :align: center

   The :class:`SimpleAppContext` class

The methods available in :class:`SimpleAppContext` and the location of their
definition are show below.


.. include:: .build/method-docs/SimpleAppContext-methods.rst

The :class:`SimpleAppContext` class provides the following functionality to your
application.

* 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 ``__albstate__`` inside each HTML form
  constructed using ``<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
  the :ref:`app-model` section, you will note where the session is loaded into and
  saved from the context.  These steps correspond to the :meth:`load_session` and
  :meth:`save_session` methods of the execution context respectively.

  In the :class:`HiddenFieldSessionMixin` class, the :meth:`load_session` method
  retrieves the encoded session data from the ``__albstate__`` field in the
  browser request.  The :meth:`save_session` method does not do anything because
  the session has already been saved into each form produced in the HTML output.

* All input fields in an HTML form which are left empty by the browser will be
  set to ``None`` when the request is merged into the local namespace.

  The :class:`NameRecorderMixin` mixin class encodes the names of all
  ``<al-input>`` fields in the form inside a hidden field named ``__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 ``__albform__`` field is
  used to detect the fields missing from the browser request.

The methods implemented in the :class:`SimpleAppContext` class are:


.. method:: SimpleAppContext.__init__(app)

   When you inherit from the :class:`SimpleAppContext` class you must call this
   constructor.

   The *app* argument is passed to the :class:`AppContext` constructor.


.. method:: SimpleAppContext.form_close()

   Invokes the :meth:`form_close` method of the :class:`NameRecorderMixin` class
   and :meth:`encode_session` of the :class:`HiddenFieldSessionMixin` class.


.. _pack-sessappcontext:

The ``SessionAppContext`` Class
-------------------------------

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.

.. _fig-sessappcontext:

.. figure:: .build/figures/sessionappcontext.*
   :align: center

   The :class:`SessionAppContext` class

The methods available in :class:`SessionAppContext` and the location of their
definition are show below.


.. include:: .build/method-docs/SessionAppContext-methods.rst

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.


.. method:: SessionAppContext.__init__(app)

   When you inherit from the :class:`SessionAppContext` class you must call this
   constructor.

   The *app* argument is passed to the :class:`AppContext` constructor.


.. _pack-sessfileappcontext:

The ``SessionFileAppContext`` Class
-----------------------------------

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.

.. _fig-sessfileappcontext:

.. figure:: .build/figures/sessionfileappcontext.*
   :align: center

   The :class:`SessionFileAppContext` class

The methods available in :class:`SessionFileAppContext` and the location of
their definition are show below.


.. include:: .build/method-docs/SessionFileAppContext-methods.rst

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.


.. method:: SessionFileAppContext.__init__(app)

   When you inherit from the :class:`SessionFileAppContext` class you must call
   this constructor.

   The *app* argument is passed to the :class:`AppContext` constructor.


.. _pack-branchingsesscontext:

The ``BranchingSessionContext`` Class
-------------------------------------

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

.. _fig-branchingsessioncontext:

.. figure:: .build/figures/branchingsessioncontext.*
   :align: center

   The :class:`BranchingSessionContext` class

The methods available in :class:`BranchingSessionContext` and the location of
their definition are show below.


.. include:: .build/method-docs/BranchingSessionContext-methods.rst

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:


.. method:: BranchingSessionContext.__init__(app)

   When you inherit from the :class:`BranchingSessionContext` class you must call
   this constructor.

   The *app* argument is passed to the :class:`AppContext` constructor.


.. method:: BranchingSessionContext.form_close()

   Invokes the :meth:`form_close` method of the :class:`NameRecorderMixin` class
   and :meth:`encode_session` of the :class:`BranchingSessionMixin` class.


.. _pack-app:

The ``Application`` Base Class
==============================

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.

.. _fig-application:

.. figure:: .build/figures/application.*
   :align: center

   The :class:`Application` class

The methods available in :class:`Application` and the location of their
definition are show below.


.. include:: .build/method-docs/Application-methods.rst

The :class:`Application` class introduces a number of new methods.


.. method:: Application.__init__(base_url)

   When you inherit from the :class:`Application` class you must call this
   constructor.

   The *base_url* argument is used as the base for URLs produced by the ``<al-a>``
   and ``<al-form>`` tags.


.. method:: Application.base_url()

   Returns the *base_url* argument which was passed to the constructor.


.. method:: Application.run(req)

   Implements the standard application run sequence as described in the
   :ref:`app-model` section.  The browser request passed as the *req* argument is
   attached to the execution context as soon as the context has been created.

   If an exception is caught then the :meth:`handle_exception` method is called
   passing the *req* argument.


.. method:: Application.format_exception()

   Retrieves the current exception from ``sys.exc_info()`` then formats and returns
   the standard Python traceback and a template interpreter traceback.


.. method:: Application.handle_exception(ctx, req)

   This implements the default exception handling for applications.  The *req*
   argument is the browser request which was passed to the :meth:`run` method.

   The method calls the :meth:`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 :attr:`locals.python_exc`
   value, and the template traceback in the :attr:`locals.html_exc` value.

   The method then tries to load the ``'uncaught_exception.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
   ``'uncaught_exception.html'`` the method writes both formatted
   exceptions as a ``<pre>`` formatted browser response.


.. method:: Application.template_traceback(tb)

   Generates a template interpreter traceback from the Python stack trace in the
   *tb* argument.


.. method:: Application.load_session(ctx)

   Calls the :meth:`load_session` method of the execution context in the *ctx*
   argument.


.. method:: Application.save_session(ctx)

   Calls the :meth:`save_session` method of the execution context in the *ctx*
   argument.


.. method:: Application.remove_session(ctx)

   Calls the :meth:`remove_session` method of the execution context in the *ctx*
   argument.


.. method:: Application.validate_request(ctx)

   Returns ``TRUE``.

   You should override this method in your application object if you need to
   validate browser requests before processing them. Returning False will prevent
   the browser request being merged into the local namespace and the page_process
   logic will not be called (see also the description of the Albatross Application
   Model in :ref:`app-model`).


.. method:: 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.


.. method:: 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.


.. method:: Application.merge_request(ctx)

   Calls the :meth:`merge_request` method of the execution context.


.. _pack-appclasses:

Application Classes:
====================


.. _pack-simpleapp:

The ``SimpleApp`` Class
-----------------------

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.

.. _fig-simpleapp:

.. figure:: .build/figures/simpleapp.*
   :align: center

   The :class:`SimpleApp` class

The methods available in :class:`SimpleApp` and the location of their definition
are show below.


.. include:: .build/method-docs/SimpleApp-methods.rst

The  :class:`SimpleApp` class defines the following methods:


.. method:: SimpleApp.__init__(base_url, template_path, start_page, secret)

   When you inherit from the :class:`SimpleApp` class you must call this
   constructor.

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


.. method:: SimpleApp.create_context()

   Returns a new instance of the :class:`SimpleAppContext` class.


.. _pack-simplesessapp:

The ``SimpleSessionApp`` Class
------------------------------

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

.. _fig-simplesessapp:

.. figure:: .build/figures/simplesessapp.*
   :align: center

   The :class:`SimpleSessionApp` class

The methods available in :class:`SimpleSessionApp` and the location of their
definition are show below.


.. include:: .build/method-docs/SimpleSessionApp-methods.rst

The :class:`SimpleSessionApp` class defines the following methods:


.. method:: SimpleSessionApp.__init__(base_url, template_path, start_page, secret, session_appid [, session_server ``= 'localhost'``] [, server_port ``= 34343``] [, session_age ``= 1800``])

   When you inherit from the :class:`SimpleSessionApp` class you must call this
   constructor.

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

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


.. method:: SimpleSessionApp.create_context()

   Returns a new instance of the :class:`SessionAppContext` class.


.. _pack-simplesessfileapp:

The ``SimpleSessionFileApp`` Class
----------------------------------

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.

.. _fig-simplesessfileapp:

.. figure:: .build/figures/simplesessfileapp.*
   :align: center

   The :class:`SimpleSessionFileApp` class

The methods available in :class:`SimpleSessionFileApp` and the location of their
definition are show below.


.. include:: .build/method-docs/SimpleSessionFileApp-methods.rst

The :class:`SimpleSessionFileApp` class defines the following methods:


.. method:: 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 *base_url* argument is used as the base for URLs produced by the ``<al-a>``
   and ``<al-form>`` tags.  The *template_path* defines the root directory where
   template files are loaded from.  The *start_page* identifies the first page that
   will be served up in a new browser session.  The *secret* argument is used to
   sign all pickles sent to the browser.

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


.. method:: SimpleSessionFileApp.create_context()

   Returns a new instance of the :class:`SessionFileAppContext` class.


.. _pack-modularapp:

The ``ModularApp`` Class
------------------------

The :class:`ModularApp` class is intended for use in applications which define
page code in a collection of Python modules.

.. _fig-modularapp:

.. figure:: .build/figures/modularapp.*
   :align: center

   The :class:`ModularApp` class

The methods available in :class:`ModularApp` and the location of their
definition are show below.


.. include:: .build/method-docs/ModularApp-methods.rst

The :class:`ModularApp` class defines the following methods:


.. method:: 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 *base_url* argument is used as the base for URLs produced by the ``<al-a>``
   and ``<al-form>`` tags.  The *module_path* argument defines the root directory
   where page modules are loaded from.  The *template_path* argument defines the
   root directory where template files are loaded from.  The *start_page*
   identifies the first page that will be served up in a new browser session.  The
   *secret* argument is used to sign all pickles sent to the browser.


.. method:: ModularApp.create_context()

   Returns a new instance of the :class:`SimpleAppContext` class.


.. _pack-modularsessapp:

The ``ModularSessionApp`` Class
-------------------------------

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.

.. _fig-modularsessapp:

.. figure:: .build/figures/modularsessapp.*
   :align: center

   The :class:`ModularSessionApp` class

The methods available in :class:`ModularSessionApp` and the location of their
definition are show below.


.. include:: .build/method-docs/ModularSessionApp-methods.rst

The :class:`ModularSessionApp` class defines the following methods:


.. method:: ModularSessionApp.__init__(base_url, module_path, template_path, start_page, secret, session_appid [, session_server ``= 'localhost'``] [, server_port ``= 34343``] [, session_age ``= 1800``])

   When you inherit from the :class:`ModularSessionApp` class you must call this
   constructor.

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

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


.. method:: ModularSessionApp.create_context()

   Returns a new instance of the :class:`SessionAppContext` class.


.. _pack-modularsessfileapp:

The ``ModularSessionFileApp`` Class
-----------------------------------

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.

.. _fig-modularsessfileapp:

.. figure:: .build/figures/modularsessfileapp.*
   :align: center

   The :class:`ModularSessionFileApp` class

The methods available in :class:`ModularSessionFileApp` and the location of
their definition are show below.


.. include:: .build/method-docs/ModularSessionFileApp-methods.rst

The :class:`ModularSessionFileApp` class defines the following methods:


.. method:: 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 *base_url* argument is used as the base for URLs produced by the ``<al-a>``
   and ``<al-form>`` tags.  The *module_path* argument defines the root directory
   where page modules are loaded from.  The *template_path* argument defines the
   root directory where template files are loaded from.  The *start_page*
   identifies the first page that will be served up in a new browser session.  The
   *secret* argument is used to sign all pickles sent to the browser.

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


.. method:: ModularSessionFileApp.create_context()

   Returns a new instance of the :class:`SessionFileAppContext` class.


.. _pack-ranmodapp:

The ``RandomModularApp`` Class
------------------------------

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.

.. _fig-randmodapp:

.. figure:: .build/figures/randmodapp.*
   :align: center

   The :class:`RandomModularApp` class

The methods available in :class:`RandomModularApp` and the location of their
definition are show below.


.. include:: .build/method-docs/RandomModularApp-methods.rst

The :class:`RandomModularApp` class defines the following methods:


.. method:: RandomModularApp.__init__(base_url, page_path, start_page, secret)

   When you inherit from the :class:`RandomModularApp` class you must call this
   constructor.

   The *base_url* argument is used as the base for URLs produced by the ``<al-a>``
   and ``<al-form>`` tags.  The *page_path* argument defines the root directory
   where page modules and template files are loaded from.  The *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 *secret* argument is used
   to  sign all pickles sent to the browser.


.. method:: RandomModularApp.create_context()

   Returns a new instance of the :class:`SimpleAppContext` class.


.. _pack-ranmodsessapp:

The ``RandomModularSessionApp`` Class
-------------------------------------

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.

.. _fig-randmodsessapp:

.. figure:: .build/figures/randmodsessapp.*
   :align: center

   The :class:`RandomModularSessionApp` class

The methods available in :class:`RandomModularSessionApp` and the location of
their definition are show below.


.. include:: .build/method-docs/RandomModularSessionApp-methods.rst

The :class:`RandomModularSessionApp` class defines the following methods:


.. method:: RandomModularSessionApp.__init__(base_url, page_path, start_page, secret, session_appid [, session_server ``= 'localhost'``] [, server_port ``= 34343``] [, session_age ``= 1800``])

   When you inherit from the :class:`RandomModularSessionApp` class you must call
   this constructor.

   The *base_url* argument is used as the base for URLs produced by the ``<al-a>``
   and ``<al-form>`` tags.  The *page_path* argument defines the root directory
   where page modules and template files are loaded from.  The *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 *secret* argument is used
   to  sign all pickles sent to the browser.

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


.. method:: RandomModularSessionApp.create_context()

   Returns a new instance of the :class:`SessionAppContext` class.


.. _pack-ranmodsessfileapp:

The ``RandomModularSessionFileApp`` Class
-----------------------------------------

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.

.. _fig-randmodsessfileapp:

.. figure:: .build/figures/randmodsessfileapp.*
   :align: center

   The :class:`RandomModularSessionFileApp` class

The methods available in :class:`RandomModularSessionFileApp` and the location
of their definition are show below.


.. include:: .build/method-docs/RandomModularSessionFileApp-methods.rst

The :class:`RandomModularSessionFileApp` class defines the following methods:


.. method:: 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 *base_url* argument is used as the base for URLs produced by the ``<al-a>``
   and ``<al-form>`` tags.  The *page_path* argument defines the root directory
   where page modules and template files are loaded from.  The *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 *secret* argument is used
   to  sign all pickles sent to the browser.

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


.. method:: RandomModularSessionFileApp.create_context()

   Returns a new instance of the :class:`SessionFileAppContext` class.