Introduction

Quixote is a Python Web application framework. It comes with an in-memory session manager, which works but is incompatible with multi-process servers (SCGI, CGI, etc). It also forgets the sessions when the Publisher quits. session2 solves these problems by providing a new session manager class and a simple back end storage API.

session2 also provides several (fully functional) persistent storage back ends:

DirectorySessionStore

Store each pickled session in a file in the designated directory. The filename is the session ID. Uses fcntl file locking.

DirectorySessionStore(directory)

DurusSessionStore

Store sessions in a Durus database.

DurusSessionStore(durus_connection)

MySQLSessionStore

Store sessions in a MySQL database.

MySQLSessionStore(mysql_connection, table='sessions')

PostgresSessionStore

Store sessions in a PostgreSQL database.

PostgresSessionStore(psycopg_connection)

ShelveSessionStore

Store sessions in a DBM database using shelve.

ShelveSessionStore(filename)

This package includes a refactored SessionManager that makes it easy to develop additional back ends, and a simplified Session class (no .is_dirty method). It supports the usual .user, .set_user() and .has_info() attributes, and you can also set your own attributes which will be saved. There's also a DictSession subclass for those who prefer setting keys rather than attributes [1].

It's quite likely that the session stores can be adapted for use with other Web frameworks; let us know if you do this so we can link to you and/or include helpful code in our package.

Getting session2

Download the latest version here: http://quixote.idyll.org/session2/session2-0.6.tar.gz

Source code browser: http://cafepy.com/quixote_extras/titus/session2/

You can also grab it directly via subversion.

Using session2

In your create_publisher function, place the following code:

# create the session store.
from session2.store.VolatileSessionStore import VolatileSessionStore
store = VolatileSessionStore()

# create the session manager.
from session2.SessionManager import SessionManager
session_manager = SessionManager(store)

# create the publisher.
from quixote.publish import Publisher
publisher = Publisher(..., session_manager.session_manager)

Each session store has different initialization requirements; see the source documentation for more information.

To use an alternate session class:

from session2.DictSession import DictSession
session_manager = SessionManager(store, DictSession)

import MySQLdb
from session2.store.MySQLSessionStore import MySQLSessionStore
from session2.SessionManager import SessionManager
from quixote.publish import Publisher
conn = MySQLdb.connect(user='USER', passwd='PASSWORD', db='DB')
store = MySQLSessionStore(conn, table='sessions')
session_manager = SessionManager(store)
publisher = Publisher(MyDirectory(), session_manager=session_manager)

class MySessionWrapper(Session):
   """Store only your user's database ID in the user variable."""
   def set_user(self, user):
      self.user = user.db_id

   def get_user(self):
      if self.user is None:   # user not set
         return None

      return database.load_user(self.user)

Features

All session stores have the following methods, which are called by the session manager: .load_session, .save_session, .delete_session, .has_session.

They also have these convenience methods:

.setup(): initializes the store. For MySQL and PostgreSQL, this creates the table. This is meant to be called in your application setup code when you deploy it on a new server.

.delete_old_sessions(minutes): deletes sessions that haven't been modified for N minutes. This is meant for your application maintenance program; e.g., a daily cron job. Only MySQLSessionStore actually deletes the sessions at this point; it's a no-op for the others.

.iter_sessions(): Return an iterable of (id, session) for all sessions in the store. This is for admin applications that want to browse the sessions. Only MySQLSessionStore currently implements this; the others raise NotImplementedError.

All stores have .is_multiprocess_safe and .is_thread_safe attributes. An application can check these flags and abort if configured inappropriately. The flags are defined as follows:

• DirectorySessionStore is multiprocess safe because it uses fcntl file locking. This limits its use to POSIX. See the fcntl caution below. It may be thread safe because it always locks-unlocks within the same method, but we don't know for sure so the attribute is false.
• DurusSessionStore is multiprocess safe. It's not thread safe because Durus isn't. With synchronization (see thread.allocate_lock) a subclass could be made safe, maybe.
• The two SQL session stores (MySQLSessionStore and PostgresSessionStore) are multiprocess safe. They are not thread safe because each connection is per-process. A subclass could use thread-specific connections or a connection pool.
• ShelveSessionStore is not multiprocess safe because it doesn't do file locking. See the "Restrictions" section for the shelve module in the Python Library Reference. It's not thread safe for the same reason. If you think about using fcntl in a subclass, see the fcntl caution below.

$ setup-store.py mysql HOST USER PASSWORD DATABASE [TABLE]
$ setup-store.py mysql '' joe sEcReT test
$ setup-store.py mysql '' joe sEcReT test Session

$ test_session2.py directory
$ test_session2.py durus
$ test_session2.py mysql
$ test_session2.py psycopg
$ test_session2.py shelve