On Wed, 2004-12-15 at 14:03 -0500, dialtone@divmod.net wrote:

Author: dialtone Date: Wed Dec 15 14:03:44 2004 New Revision: 952

Modified: trunk/nevow/inevow.py Log: adding documentation for inevow.ISession

Great stuff! I'm just about to eat dinner so this is a bit rushed ... I think we should differentiate between a typical session and a guard/cred session. Most applications don't (and probably shouldn't) care about the cred side of things except for some way to locate the avatar. It also looks like there's a good case for extracting a IComponentized interface. Perhaps that's already been done for twisted 2? So, how about a class hierarchy more like: class IComponentized(Interface): pass class ISession(IComponentized): pass class I(Guard|Cred)Session(ISession): pass

From the (newly) current ISession class ...

setComponent, getComponent, unsetComponent, removeComponent would be IComponentized methods, although unsetComponent looks unnecessary unless it's the opposite of setComponent and there should also be an addComponent. getLoggedInRoot, resourceForPortal, setResourceForPortal, portalLogout, are IGuardSession methods. However, getLoggedInRoot sounds strange, and resourceForPortal and setResourceForPortal sound like guard implementation. setLifetime, notifyOnExpire, expire, touch, checkExpired are ISession methods. However, IIRC checkExpired is an implementation method used as the timed callback to automatically expire individual sessions. Finally, of the attributes listed in the class docstring, I think only uid and guard are part of the interface and guard should be part of IGuardSession. Hope that makes sense and that I didn't miss anything. What do others think? Cheers, Matt

Modified: trunk/nevow/inevow.py ============================================================================== --- trunk/nevow/inevow.py (original) +++ trunk/nevow/inevow.py Wed Dec 15 14:03:44 2004 @@ -378,13 +378,94 @@ """A web session

You can locate a Session object to represent a unique web session using - ctx.locate(ISession). This default session implementation uses cookies to + ISession(ctx). This default session implementation uses cookies to store a session identifier in the user's browser. - + + guard: SessionWrapper object + uid: Session uid + expireCallbacks: callbacks for expiration event + checkExpiredID + portals: portals in which the session is logged in + TODO: Need better docs; what's a session and why and how do you use it """ - + def getLoggedInRoot(self): + """Get the most-recently-logged-in avatar. + """ + + def resourceForPortal(self, port): + """Gather the resource set for the portal port + """ + + def setResourceForPortal(self, rsrc, port, logout): + """Set returned resource when asking for something in portal port + logout is called when logged out from the resource + """ + + def portalLogout(self, port): + """Logout from portal port + """ + + def setLifetime(self, lifetime): + """Set the approximate lifetime of this session, in seconds. + + This is highly imprecise, but it allows you to set some general + parameters about when this session will expire. A callback will be + scheduled each 'lifetime' seconds, and if I have not been 'touch()'ed + in half a lifetime, I will be immediately expired. + + If you need to change the lifetime of all the sessions change sessionsLifeTime + attribute in class guard.SessionWrapper + """ + + def notifyOnExpire(self, callback): + """Call this callback when the session expires or logs out. + """ + + def expire(self): + """Expire/logout of the session. + """ + + def touch(self): + """Refresh the session + """ + + def checkExpired(self): + """ Check expiration state for the session + """ + + def setComponent(self): + """ + Add a component to me, for all appropriate interfaces. + """ + + def getComponent(self, interface, registry=None, default=None): + """Create or retrieve an adapter for the given interface. + + If such an adapter has already been created, retrieve it from the cache + that this instance keeps of all its adapters. Adapters created through + this mechanism may safely store system-specific state. + + If you want to register an adapter that will be created through + getComponent, but you don't require (or don't want) your adapter to be + cached and kept alive for the lifetime of this Componentized object, + set the attribute 'temporaryAdapter' to True on your adapter class. + + If you want to automatically register an adapter for all appropriate + interfaces (with addComponent), set the attribute 'multiComponent' to + True on your adapter class. + """ + + def unsetComponent(self, interfaceClass): + """Remove my component specified by the given interface class.""" + + def removeComponent(self, component): + """ + Remove the given component from me entirely, for all interfaces for which + it has been registered.

+ @return: a list of the interfaces that were removed. + """

class IRemainingSegments(compy.Interface): """During the URL traversal process, requesting this from the context

_______________________________________________ Nevow-commits mailing list Nevow-commits@divmod.org http://divmod.org/users/mailman.twistd/listinfo/nevow-commits