Added FileSession documentation. The layout for this section in the PDF

format is a little strange but it is not a show stopper.
Ref MODPYTHON-45.

Doc/modpython4.tex

@@ -1869,8 +1869,10 @@ \section{\module{Session} -- Session Management\label{pyapi-sess}}
 sessions across requests.
 
 The module contains a \class{BaseSession} class, which is not meant to
-be used directly (it provides no means of storing a session), and a
-\class{DbmSession} class, which uses a dbm to store sessions. 
+be used directly (it provides no means of storing a session), 
+\class{DbmSession} class, which uses a dbm to store sessions, and
+\class{FileSession} class, which uses individual files to store
+sessions.
 
 The \class{BaseSession} class also provides session locking, both
 across processes and threads. For locking it uses APR global_mutexes
@@ -2055,10 +2057,108 @@ \subsection{Classes\label{pyapi-sess-classes}}
 
 \end{classdesc}
 
-\begin{classdesc}{FileSession}{req, \optional{, sid, secret, timeout, lock, fast_cleanup, verify_cleanup, grace_period}}
+\begin{classdesc}{FileSession}{req, \optional{, sid, secret, timeout, lock, fast_cleanup, verify_cleanup}}
 
-  This class provides session storage using a separate file for each 
-  session.
+  New in version 3.2.0.
+
+  This class provides session storage using a separate file for each
+  session. It is a subclass of \module{BaseSession}.
+
+  Session data is stored in a separate file for each session. These 
+  files are not deleted when the server process is stopped, so
+  sessions are persistent across server restarts.  
+  The session files are saved in a directory named mp_sess in the 
+  temporary directory returned by the \code{tempfile.gettempdir()} 
+  standard library function. An alternate path can be set using 
+  \code{PythonOption session_directory /path/to/directory}. This
+  directory must exist and be readable and writeable by the apache
+  process.
+
+  Expired session files are periodically removed by the cleanup
+  mechanism. The behaviour of the cleanup can be controlled using the 
+  \var{fast_cleanup} and \var{verify_cleanup} parameters, as well as 
+  \var{PythonOption session_grace_period} and
+  \var{PythonOption session_cleanup_time_limit}.
+
+  \begin{itemize}
+  \item[\var{fast_cleanup}]
+    A boolean value used to turn on FileSession cleanup optimization.
+    Default is \var{True} and will result in reduced cleanup time when
+    there are a large number of session files.
+
+    When \var{fast_cleanup} is True, the modification time for the session
+    file is used to determine if it is a candidate for deletion.
+    If \code{(current_time - file_modification_time) > (timeout + grace_period)},
+    the file will be a candidate for deletion. If \var{verify_cleanup}
+    is False, no futher checks will be made and the file will be
+    deleted.
+
+    If \var{fast_cleanup} is False, the session file will unpickled and
+    it's timeout value used to determine if the session is a candidate for
+    deletion. \var{fast_cleanup} = False implies \var{verify_cleanup} =
+    True.
+
+    The timeout used in the fast_cleanup calculation is same as the
+    timeout for the session in the current request running the
+    filesession_cleanup. If your session objects are not using the same
+    timeout, or you are manually setting the timeout for a particular
+    session with \code{set_timeout()}, you will need to set 
+    \var{verify_cleanup} = True.
+
+    The value of \var{fast_cleanup} can also be set using
+    \code{PythonOption session_fast_cleanup}.
+
+  \item[\var{verify_cleanup}]
+    Boolean value used to optimize the FileSession cleanup process.
+    Default is \code{True}.
+
+    If \var{verify_cleanup} is True, the session file which is being 
+    considered for deletion will be unpickled and its timeout value
+    will be used to decide if the file should be deleted. 
+
+    When \var{verify_cleanup} is False, the timeout value for the current
+    session will be used in to determine if the session has expired. In
+    this case, the session data will not be read from disk, which can
+    lead to a substantial performance improvement when there are a large
+    number of session files, or where each session is saving a large 
+    amount of data. However this may result in valid sessions being
+    deleted if all the sessions are not using a the same timeout value.
+
+    The value of \var{verify_cleanup} can also be set using
+    \code{PythonOption session_verify_cleanup}
+
+  \item[\var{PythonOption session_cleanup_time_limit [value]}]
+    Integer value in seconds. Default is 2 seconds.
+
+    Session cleanup could potentially take a long time and be both cpu
+    and disk intensive, depending on the number of session files and if
+    each file needs to be read to verify the timeout value. To avoid
+    overloading the server, each time filesession_cleanup is called it
+    will run for a maximum of \var{session_cleanup_time_limit} seconds.
+    Each cleanup call will resume from where the previous call left off
+    so all session files will eventually be checked.
+
+    Setting \var{session_cleanup_time_limit} to 0 will disable this 
+    feature and filesession_cleanup will run to completion each time it
+    is called.
+
+  \item[\var{PythonOption session_grace_period [value]}]
+    Integer value in seconds. Default is 240 seconds. This value is added
+    to the session timeout in determining if a session file should be 
+    deleted.
+
+    There is a small chance that a the cleanup for a given session file
+    may occur at the exact time that the session is being accessed by
+    another request. It is possible under certain circumstances for that
+    session file to be saved in the other request only to be immediately 
+    deleted by the cleanup. To avoid this race condition, a session is
+    allowed a \var{grace_period} before it is considered for deletion by
+    the cleanup.  As long as the grace_period is longer that the time it
+    takes to complete the request (which should normally be less than 1
+    second), the session will not be mistakenly deleted by the cleanup.
+
+    The default value should be sufficient for most applications.
+  \end{itemize}
 
 \end{classdesc}
 
@@ -2075,6 +2175,28 @@ \subsection{Classes\label{pyapi-sess-classes}}
 
 \end{classdesc}
 
+\subsection{Examples\label{pyapi-sess-example}}
+The following example demonstrates a simple hit counter.
+
+    \begin{verbatim}
+
+from mod_python import Session
+
+def handler(req):
+    session = Session.Session(req)
+
+    try:
+        session['hits'] += 1
+    except:
+        session['hits'] = 1
+
+    session.save()
+
+    req.content_type = 'text/plain'
+    req.write('Hits: %d\n' % session['hits'])
+    return apache.OK 
+    \end{verbatim}
+
 \section{\module{psp} -- Python Server Pages\label{pyapi-psp}}
 \declaremodule[psp]{extension}{psp}
 \modulesynopsis{Python Server Pages}