Notes for developers using the pre-0.5 session management API
-------------------------------------------------------------

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.5 2002/06/10 15:09:55 gward Exp $
