<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="modpython.css" type='text/css' />
<link rel="first" href="modpython.html" title='Mod_python Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="pyapi-sess-example.html" />
<link rel="prev" href="pyapi-sess.html" />
<link rel="parent" href="pyapi-sess.html" />
<link rel="next" href="pyapi-sess-example.html" />
<meta name='aesop' content='information' />
<title>4.8.1 Classes</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.8 Session - Session"
href="pyapi-sess.html"><img src='previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.8 Session - Session"
href="pyapi-sess.html"><img src='up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.8.2 Examples"
href="pyapi-sess-example.html"><img src='next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Mod_python Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='blank.png'
border='0' height='32' alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
href="genindex.html"><img src='index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="pyapi-sess.html">4.8 Session - Session</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="pyapi-sess.html">4.8 Session - Session</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pyapi-sess-example.html">4.8.2 Examples</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION006810000000000000000"></A><A NAME="pyapi-sess-classes"></A>
<BR>
4.8.1 Classes
</H2>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-238' xml:id='l2h-238' class="function">Session</tt></b>(</nobr></td>
<td><var>req</var><big>[</big><var>, sid, secret, timeout, lock</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
<P>
<tt class="function">Session()</tt> takes the same arguments as <tt class="class">BaseSession</tt>.
<P>
This function returns a instance of the default session class. The
session class to be used can be specified using <var>PythonOption
mod_python.session.session_type value</var>, where <var>value</var> is one of
<tt class="class">DbmSession</tt>, <tt class="class">MemorySession</tt> or <tt class="class">FileSession</tt>.
Specifying custom session classes using <code>PythonOption</code> session is
not yet supported.
<P>
If session type option is not found, the function queries the MPM and
based on that returns either a new instance of <tt class="class">DbmSession</tt> or
<tt class="class">MemorySession</tt>. <tt class="class">MemorySession</tt> will be used if the MPM is
threaded and not forked (such is the case on Windows), or if it threaded,
forked, but only one process is allowed (the worker MPM can be configured
to run this way). In all other cases <tt class="class">DbmSession</tt> is used.
<P>
Note that on Windows if you are using multiple Python interpreter
instances and you need sessions to be shared between applications
running within the context of the distinct Python interpreter
instances, you must specifically indicate that <tt class="class">DbmSession</tt>
should be used, as <tt class="class">MemorySession</tt> will only allow a session
to be valid within the context of the same Python interpreter instance.
<P>
Also note that the option name <code>mod_python.session.session_type</code>
only started to be used from mod_python 3.3 onwards. If you need to
retain compatability with older versions of mod_python, you should
use the now obsolete <code>session</code> option instead.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-239' xml:id='l2h-239' class="class">BaseSession</tt></b>(</nobr></td>
<td><var>req</var><big>[</big><var>, sid, secret, timeout, lock</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
<P>
This class is meant to be used as a base class for other classes
that implement a session storage mechanism. <var>req</var> is a required
reference to a mod_python request object.
<P>
<tt class="class">BaseSession</tt> is a subclass of <tt class="class">dict</tt>. Data can be
stored and retrieved from the session by using it as a
dictionary.
<P>
<var>sid</var> is an optional session id; if provided, such a session
must already exist, otherwise it is ignored and a new session with a
new sid is created. If <var>sid</var> is not provided, the object will
attempt to look at cookies for session id. If a sid is found in
cookies, but it is not previously known or the session has expired,
then a new sid is created. Whether a session is ``new'' can be
determined by calling the <tt class="method">is_new()</tt> method.
<P>
Cookies generated by sessions will have a path attribute which is
calculated by comparing the server <code>DocumentRoot</code> and the directory
in which the <code>PythonHandler</code> directive currently in effect was
specified. E.g. if document root is <span class="file">/a/b/c</span> and the directory
<code>PythonHandler</code> was specified was <span class="file">/a/b/c/d/e</span>, the path will be
set to <span class="file">/d/e</span>.
<P>
The deduction of the path in this way will only work though where the
<code>Directory</code> directive is used and the directory is actually within
the document root. If the <code>Location</code> directive is used or the
directory is outside of the document root, the path will be set to
<span class="file">/</span>. You can force a specific path by setting the
<code>mod_python.session.application_path</code> option ("<tt class="samp">PythonOption
mod_python.session.application_path /my/path</tt>" in server configuration).
<P>
Note that prior to mod_python 3.3, the option was <code>ApplicationPath</code>.
If your system needs to be compatible with older versions of mod_python,
you should continue to use the now obsolete option name.
<P>
The domain of a cookie is by default not set for a session and as such
the session is only valid for the host which generated it. In order to
have a session which spans across common sub domains, you can specify the
parent domain using the <code>mod_python.session.application_domain</code>
option ("<tt class="samp">PythonOption mod_python.session.application_domain
mod_python.org</tt>" in server configuration).
<P>
When a <var>secret</var> is provided, <tt class="class">BaseSession</tt> will use
<tt class="class">SignedCookie</tt> when generating cookies thereby making the
session id almost impossible to fake. The default is to use plain
<tt class="class">Cookie</tt> (though even if not signed, the session id is
generated to be very difficult to guess).
<P>
A session will timeout if it has not been accessed and a save performed,
within the <var>timeout</var> period. Upon a save occuring the time of last
access is updated and the period until the session will timeout be reset.
The default <var>timeout</var> period is 30 minutes. An attempt to load an
expired session will result in a ``new'' session.
<P>
The <var>lock</var> argument (defaults to 1) indicates whether locking
should be used. When locking is on, only one session object with a
particular session id can be instantiated at a time.
<P>
A session is in ``new'' state when the session id was just
generated, as opposed to being passed in via cookies or the
<var>sid</var> argument.
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-240' xml:id='l2h-240' class="method">is_new</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Returns 1 if this session is new. A session will also be ``new''
after an attempt to instantiate an expired or non-existent
session. It is important to use this method to test whether an
attempt to instantiate a session has succeeded, e.g.:
<div class="verbatim"><pre>
sess = Session(req)
if sess.is_new():
# redirect to login
util.redirect(req, 'http://www.mysite.com/login')
</pre></div>
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-241' xml:id='l2h-241' class="method">id</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Returns the session id.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-242' xml:id='l2h-242' class="method">created</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Returns the session creation time in seconds since beginning of
epoch.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-243' xml:id='l2h-243' class="method">last_accessed</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Returns last access time in seconds since beginning of epoch.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-244' xml:id='l2h-244' class="method">timeout</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Returns session timeout interval in seconds.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-245' xml:id='l2h-245' class="method">set_timeout</tt></b>(</nobr></td>
<td><var>secs</var>)</td></tr></table></dt>
<dd>
Set timeout to <var>secs</var>.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-246' xml:id='l2h-246' class="method">invalidate</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
This method will remove the session from the persistent store and
also place a header in outgoing headers to invalidate the session
id cookie.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-247' xml:id='l2h-247' class="method">load</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Load the session values from storage.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-248' xml:id='l2h-248' class="method">save</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
This method writes session values to storage.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-249' xml:id='l2h-249' class="method">delete</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Remove the session from storage.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-250' xml:id='l2h-250' class="method">init_lock</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
This method initializes the session lock. There is no need to ever
call this method, it is intended for subclasses that wish to use
an alternative locking mechanism.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-251' xml:id='l2h-251' class="method">lock</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Locks this session. If the session is already locked by another
thread/process, wait until that lock is released. There is no need
to call this method if locking is handled automatically (default).
<P>
This method registeres a cleanup which always unlocks the session
at the end of the request processing.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-252' xml:id='l2h-252' class="method">unlock</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
Unlocks this session. (Same as <tt class="method">lock()</tt> - when locking is
handled automatically (default), there is no need to call this
method).
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-253' xml:id='l2h-253' class="method">cleanup</tt></b>(</nobr></td>
<td><var></var>)</td></tr></table></dt>
<dd>
This method is for subclasses to implement session storage
cleaning mechanism (i.e. deleting expired sessions, etc.). It will
be called at random, the chance of it being called is controlled
by <tt class="constant">CLEANUP_CHANCE</tt> <tt class="module">Session</tt> module variable
(default 1000). This means that cleanups will be ordered at random
and there is 1 in 1000 chance of it happening. Subclasses
implementing this method should not perform the (potentially time
consuming) cleanup operation in this method, but should instead
use <tt class="method">req.register_cleanup</tt> to register a cleanup which will
be executed after the request has been processed.
</dl>
<P>
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-254' xml:id='l2h-254' class="class">DbmSession</tt></b>(</nobr></td>
<td><var>req, </var><big>[</big><var>, dbm, sid, secret, dbmtype, timeout, lock</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
<P>
This class provides session storage using a dbm file. Generally, dbm
access is very fast, and most dbm implementations memory-map files
for faster access, which makes their performance nearly as fast as
direct shared memory access.
<P>
<var>dbm</var> is the name of the dbm file (the file must be writable by
the httpd process). This file is not deleted when the server process
is stopped (a nice side benefit of this is that sessions can survive
server restarts). By default the session information is stored in a
dbmfile named <span class="file">mp_sess.dbm</span> and stored in a temporary directory
returned by <code>tempfile.gettempdir()</code> standard library
function. An alternative directory can be specified using
<code>PythonOption mod_python.dbm_session.database_directory
/path/to/directory</code>. The path and filename can can be overridden by
setting <code>PythonOption mod_python.dbm_session.database_filename
filename</code>.
<P>
Note that the above names for the <code>PythonOption</code> settings were
changed to these values in mod_python 3.3. If you need to retain
compatability with older versions of mod_python, you should continue
to use the now obsolete <code>session_directory</code> and <code>session_dbm</code>
options.
<P>
The implementation uses Python <tt class="module">anydbm</tt> module, which will
default to <tt class="module">dbhash</tt> on most systems. If you need to use a
specific dbm implementation (e.g. <tt class="module">gdbm</tt>), you can pass that
module as <var>dbmtype</var>.
<P>
Note that using this class directly is not cross-platform. For best
compatibility across platforms, always use the <tt class="function">Session()</tt>
function to create sessions.
<P>
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-255' xml:id='l2h-255' class="class">FileSession</tt></b>(</nobr></td>
<td><var>req, </var><big>[</big><var>, sid, secret, timeout, lock, fast_cleanup, verify_cleanup</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
<P>
New in version 3.2.0.
<P>
This class provides session storage using a separate file for each
session. It is a subclass of <tt class="module">BaseSession</tt>.
<P>
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()</code>
standard library function. An alternate path can be set using
<code>PythonOption mod_python.file_session.database_directory
/path/to/directory</code>. This directory must exist and be readable and
writeable by the apache process.
<P>
Note that the above name for the <code>PythonOption</code> setting was
changed to these values in mod_python 3.3. If you need to retain
compatability with older versions of mod_python, you should continue
to use the now obsolete <code>session_directory</code> option.
<P>
Expired session files are periodically removed by the cleanup mechanism.
The behaviour of the cleanup can be controlled using the
<var>fast_cleanup</var> and <var>verify_cleanup</var> parameters, as well as
<var>PythonOption mod_python.file_session.cleanup_time_limit</var> and
<var>PythonOption mod_python.file_session.cleanup_grace_period</var>.
<P>
<UL>
<LI><var>fast_cleanup</var>
A boolean value used to turn on FileSession cleanup optimization.
Default is <var>True</var> and will result in reduced cleanup time when
there are a large number of session files.
<P>
When <var>fast_cleanup</var> 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)</code>,
the file will be a candidate for deletion. If <var>verify_cleanup</var>
is False, no futher checks will be made and the file will be
deleted.
<P>
If <var>fast_cleanup</var> 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</var> = False implies <var>verify_cleanup</var> =
True.
<P>
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()</code>, you will need to set
<var>verify_cleanup</var> = True.
<P>
The value of <var>fast_cleanup</var> can also be set using
<code>PythonOption mod_python.file_session.enable_fast_cleanup</code>.
<P>
</LI>
<LI><var>verify_cleanup</var>
Boolean value used to optimize the FileSession cleanup process.
Default is <code>True</code>.
<P>
If <var>verify_cleanup</var> 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.
<P>
When <var>verify_cleanup</var> 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.
<P>
The value of <var>verify_cleanup</var> can also be set using
<code>PythonOption mod_python.file_session.verify_session_timeout</code>.
<P>
</LI>
<LI><var>PythonOption mod_python.file_session.cleanup_time_limit [value]</var>
Integer value in seconds. Default is 2 seconds.
<P>
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</var> seconds.
Each cleanup call will resume from where the previous call left off
so all session files will eventually be checked.
<P>
Setting <var>session_cleanup_time_limit</var> to 0 will disable this
feature and filesession_cleanup will run to completion each time it
is called.
<P>
</LI>
<LI><var>PythonOption mod_python.file_session.cleanup_grace_period [value]</var>
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.
<P>
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</var> 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.
<P>
The default value should be sufficient for most applications.
</LI>
</UL>
<P>
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-256' xml:id='l2h-256' class="class">MemorySession</tt></b>(</nobr></td>
<td><var>req, </var><big>[</big><var>, sid, secret, timeout, lock</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
<P>
This class provides session storage using a global dictionary. This
class provides by far the best performance, but cannot be used in a
multi-process configuration, and also consumes memory for every
active session. It also cannot be used where multiple Python interpreters
are used within the one Apache process and it is necessary to share
sessions between applications running in the distinct interpreters.
<P>
Note that using this class directly is not cross-platform. For best
compatibility across platforms, always use the <tt class="function">Session()</tt>
function to create sessions.
<P>
</dl>
<P>
<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.8 Session - Session"
href="pyapi-sess.html"><img src='previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.8 Session - Session"
href="pyapi-sess.html"><img src='up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.8.2 Examples"
href="pyapi-sess-example.html"><img src='next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Mod_python Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='blank.png'
border='0' height='32' alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
href="genindex.html"><img src='index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="pyapi-sess.html">4.8 Session - Session</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="pyapi-sess.html">4.8 Session - Session</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pyapi-sess-example.html">4.8.2 Examples</A>
</div>
</div>
<hr />
<span class="release-info">Release 3.3.1, documentation updated on January 29, 2007.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
15533144ea879a3ee7f2cdcbb31e4859
>
files
>
119
