[Commits] python.it commit r199 - twisted/trunk/contrib/nevow/doc/txt

[commit a svn.python.it]

Author: manlio
Date: Thu Jul 20 22:53:57 2006
New Revision: 199

Added:
   twisted/trunk/contrib/nevow/doc/txt/nevow-sessions.txt
Log:
sessioni

Added: twisted/trunk/contrib/nevow/doc/txt/nevow-sessions.txt
==============================================================================
--- (empty file)
+++ twisted/trunk/contrib/nevow/doc/txt/nevow-sessions.txt	Thu Jul 20 22:53:57 2006
@@ -0,0 +1,222 @@
+============================
+Sessions? What are sessions?
+============================
+
+HTTP Protocol
+-------------
+
+First some notes about the HTTP protocol, what means to have a
+stateless protocol and what is a REST architecture.
+
+Please note that not all Nevow's users are expert of HTTP.
+
+XXX:
+  
+ Maybe this section should be in another chapter.
+
+Now it whould help to have some use cases of a stateless protocol.
+Is is important to show a pure REST solution to problems that are
+usually solved with sessions.
+
+XXX:
+  
+  Here can go a simple example of HTTP Basic Authentication, with some
+  mixin class for the rend.Page that force authentication on every
+  page.
+
+  Show the advantages of this solution and it's disavantage.
+
+Sessions can provide a valid alternative to pure REST solutions, but
+**add** simple examples that are not possible without sessions.
+
+
+HTTP Cookies
+------------
+
+The HTTP solution for adding state are Cookies.
+
+*Again*, don't assume that users are expert of Cookies, so explain what
+cookies are **and** what spec to use.
+
+Now explain the interface offered by Twisted Web/Nevow to Cookie:
+  
+  IRequest.addCookie and IRequest.getCookie -> describe
+
+Give some example about how to use coockies directly in your code (using
+the cookie name as dictionary key).
+
+
+Nevow Sessions
+--------------
+
+This is an higher level interface to sessions. The default
+implementation uses Cookies.
+
+XXX:
+
+  this means that it is possible to support sessions without using
+  cookies?
+
+The interface is INevow.ISession -> describe
+
+XXX:
+
+  In the source code there are **two** ISession classes.
+
+  Moreover there is this comment in
+  appserver.NevowRequest.SetSession::
+
+    ## temporary until things settle down with the new sessions
+
+  What means?
+
+A session is obtained with:
+
+  IRequest.getSession(self, sessionInterface=None)
+
+For now let's ignore the sessionInterface argument.
+
+When calling getSession the first time, a session cookie will be
+created.
+
+The name of the cookie is TWISTED_SESSION.
+
+XXX:
+  
+   Can I change this name? No: it is hard written in the source code.
+
+   
+
+How to use sessions
++++++++++++++++++++
+
+Sessions can be used in several ways.
+
+* Using the session object to store state.
+
+    Here comes the **advantages** of a dynamic language like Python.
+    Since objects are dinamic you can add variables to instances.
+
+    Example::
+        
+        def data_counter(self, ctx, data):
+           session = inevow.ISession(ctx)
+           count = getattr(session, "count", 1)
+           session.count = count + 1
+        
+           return count
+
+
+    Note that you need to proper initialize your variable.
+
+    This example also show the **advantages** of an asynchronous
+    framework.
+    No need to serialize the session or to use locks.
+
+    XXX:
+
+      But this is hidden from users of, say, mod_python (?).
+
+
+* Using session.uid as a key to loock up a dictionary 
+  (why one want to do so?).
+
+* Using session.sessionNamespaces. This will return a dictionary.
+
+    Example::
+
+        def data_counter(self, ctx, data):
+           session = inevow.ISession(ctx)
+           d = session.sessionNamespaces
+            
+           d["count"] = d.setdefault("count", 0)
+           d["count"] += 1
+
+           return d["count"]
+
+    XXX:
+
+       This attribute is not documented. What is it for?
+ 
+  
+Advanced Session usage
+++++++++++++++++++++++
+
+
+XXX:
+ 
+  documentation stolen from 
+  http://twistedmatrix.com/projects/web/documentation/howto/picturepile.html#auto2
+
+Since only one Session exists per user for all applications on the
+server, the Session object is Componentized, and each application adds
+adapters to contain their own state and behaviour, as explained in the
+Components documentation. So, we start with an interface, and a class
+that implements it, and registration of our class upon Session::
+
+  from zope.interface import Interface, implements
+
+  class IPreferences(Interface):
+      pass
+
+  class Preferences:
+      implements(IPreferences)
+    
+  components.registerAdapter(Preferences, server.Session, IPreferences)
+
+
+We're just going to store data on this class, so no methods are defined.
+
+We can use this session object to store user preference, like
+thumbnail size::
+
+
+  def render_thumbnail(self, ctx, data):
+     request = inevow.IRequest(ctx)
+
+     prefs = request.getSession(IPreferences)
+     size = getattr(prefs, 'size','200')
+     
+     return ctx.tag[a.img(src="data/", width=size, height=size)]
+  
+XXX:
+
+  The example does not works. How to use componentized sessions?
+
+
+Advanced session control
+++++++++++++++++++++++++
+
+Cookies (and thus Nevow sessions) offer several options to fine control
+its behaviour.
+
+On of this is the path where cookie should be used. This is not
+controllable with Session.
+
+An important property is coockie's lifetime.
+
+XXX:
+  
+  In the interface documentation for ISession there is a setLifetime
+  method, but this is **not** implemented (and it references Guard).
+
+XXX:
+
+  It seems that Twisted set only the `path` property on session,
+  ignoring `expires`, `domain`, `max_age`, `comment` and `secure`
+
+
+When Twisted creates a session, it checks every 30 minutes that it is
+up to date.
+The session object has a lastModified attributes, controlled on the
+server.
+
+You che can explicitly call the metod checkExpired, but it will expire the
+session only if has not been touched in 15 minutes.
+
+All this constants are **hard written** in the code.
+
+A nice feature of Session is that you can register a callback to be
+called when the session expires, just use the method::
+
+  notifyOnExpire(callback)