Upgrading to Quixote 0.5 Session Management
===========================================

The Quixote session management interface underwent lots of change and
cleanup with Quixote 0.5.  It was previously undocumented (apart from
docstrings in the code), so we thought that this was a good opportunity
to clean up the interface.  Nevertheless, those brave souls who got
session management working just by reading the code are in for a bit of
suffering; this brief note should help clarify things.  The definitive
documentation for session management is session-mgmt.txt -- you should
start there.


Attribute renamings and pickled objects
---------------------------------------

Most attributes of the standard Session class were made private in order
to reduce collisions with subclasses.  The downside is that pickled
Session objects will break.  You might want to (temporarily) modify
session.py and add this method to Session::

    def __setstate__ (self, dict):
        # Update for attribute renamings made in rev. 1.51.2.3
        # (between Quixote 0.4.7 and 0.5).
        self.__dict__.update(dict)
        if hasattr(self, 'remote_address'):
            self.__remote_address = self.remote_address
            del self.remote_address
        if hasattr(self, 'creation_time'):
            self.__creation_time = self.creation_time
            del self.creation_time
        if hasattr(self, 'access_time'):
            self.__access_time = self.access_time
            del self.access_time
        if hasattr(self, 'form_tokens'):
            self._form_tokens = self.form_tokens
            del self.form_tokens

However, if your sessions were pickled via ZODB, this may not work.  (It
didn't work for us.)  In that case, you'll have to add something like
this to your class that inherits from both ZODB's Persistent and
Quixote's Session::

    def __setstate__ (self, dict):
        # Blechhh!  This doesn't work if I put it in Quixote's
        # session.py, so I have to second-guess how Python
        # treats "__" attribute names.
        self.__dict__.update(dict)
        if hasattr(self, 'remote_address'):
            self._Session__remote_address = self.remote_address
            del self.remote_address
        if hasattr(self, 'creation_time'):
            self._Session__creation_time = self.creation_time
            del self.creation_time
        if hasattr(self, 'access_time'):
            self._Session__access_time = self.access_time
            del self.access_time
        if hasattr(self, 'form_tokens'):
            self._form_tokens = self.form_tokens
            del self.form_tokens

It's not pretty, but it worked for us.


Cookie domains and paths
------------------------

The session cookie config variables -- ``COOKIE_NAME``,
``COOKIE_DOMAIN``, and ``COOKIE_PATH`` -- have been renamed to
``SESSION_COOKIE_*`` for clarity.

If you previously set the config variable ``COOKIE_DOMAIN`` to the name
of your server, this is most likely no longer necessary -- it's now fine
to leave ``SESSION_COOKIE_DOMAIN`` unset (ie. ``None``), which
ultimately means browsers will only include the session cookie in
requests to the same server that sent it to them in the first place.

If you previously set ``COOKIE_PATH``, then you should probably preserve
your setting as ``SESSION_COOKIE_PATH``.  The default of ``None`` means
that browsers will only send session cookies with requests for URIs
under the URI that originally resulted in the session cookie being sent.
See session-mgmt.txt and RFCs 2109 and 2965.

If you previously set ``COOKIE_NAME``, change it to
``SESSION_COOKIE_NAME``.


$Id: session-upgrade.txt,v 1.6 2002/10/02 15:32:22 gward Exp $